WPBakery is a popular page builder that gives you lots of options for customizing your WordPress site. But sometimes, you need functionality that doesn’t exist in the standard elements. That’s where custom WPBakery elements come in handy.
Creating custom elements might seem intimidating if you haven’t done it before, but it’s actually pretty straightforward once you understand the basics. Here’s how to build your own custom WPBakery elements.
What are WordPress elements?
In WordPress, an element is essentially a wrapper that sits on top of your custom code. It provides a consistent interface and protects your code when the underlying system changes or gets updated.
Elements help developers avoid compatibility issues by providing a stable foundation that all plugins can work with, regardless of version differences.
Why create custom WPBakery elements?
Custom elements give you several advantages over using the standard ones that come with WPBakery.
- Complete control – You can design exactly what you want without being limited by pre-built options.
- Reusability – Once you create an element, you can use it across different projects without rebuilding it from scratch.
- Commercial potential – If you create useful elements, you can package them as add-ons and sell them to other users.
- Theme integration – Custom elements can be built directly into your themes, giving clients access to specialized functionality.
Understanding WPBakery shortcodes
Before diving into custom elements, you need to understand that WPBakery elements are essentially WordPress shortcodes with a visual interface.
Shortcodes are short pieces of code wrapped in square brackets that perform specific functions on your website. When you insert a shortcode like into a page or post, it gets replaced with the actual functionality when the page loads.
WPBakery takes these shortcodes and gives them a drag-and-drop interface, making them easier to use for people who don’t want to work with code directly.
Where to put your custom element code
You have a couple of options for where to place your custom element code.
- Use WPBakery’s Shortcode Mapper – This built-in feature lets you add third-party shortcodes to the element list. It’s good for simple integrations.
- Add to functions.php – You can put your code in your theme’s functions.php file, but this can get messy if you have multiple custom elements.
- Create a separate file – The cleanest approach is to create a new folder called “vc-components” and put your custom elements in separate files within that folder. This keeps everything organized and makes it easier to manage multiple elements.
Creating a custom WPBakery element
Here’s the basic process for creating a custom element.
Step 1 – Set up the element structure
First, you need to create a class that extends WPBakeryShortCode. This gives your element access to all the standard WPBakery functionality.
if ( ! class_exists( 'VcSodaBlockquote' ) ) {
class VcSodaBlockquote extends WPBakeryShortCode {
// Initialize component
function __construct() {
add_action( 'init', array( $this, 'create_shortcode' ), 999 );
add_shortcode( 'vc_soda_blockquote', array( $this, 'render_shortcode' ) );
}
// Map Component
public function create_shortcode() {
// Code in the next step
}
// Render Component
public function render_shortcode( $atts, $content, $tag ) {
// Code in the next step
}
}
}
new VcSodaBlockquote();Step 2 – Create the shortcode mapping
Use WPBakery’s vc_map function to define how your element appears in the page builder interface. This is where you set up the fields that users will see when they configure your element.
public function create_shortcode() {
// Stop all if VC is not enabled
if ( !defined( 'WPB_VC_VERSION' ) ) {
return;
}
// Map blockquote with vc_map()
vc_map( array(
'name' => __( 'Blockquote', 'sodomedia' ),
'base' => 'vc_soda_blockquote',
'description' => __( 'Quote author', 'sodomedia' ),
'category' => __( 'SodoMedia Modules', 'sodomedia' ),
'icon' => get_template_directory_uri().'/framework/admin/img/vc/',
'params' => array(
array(
'type' => 'textfield',
'heading' => __( 'Author Quote', 'sodomedia' ),
'param_name' => 'quote_author',
'value' => __( 'Quote Author', 'sodomedia' ),
'description' => __( 'Add Author Quote', 'sodomedia' ),
),
),
));
}Step 3 – Render the shortcode output
Create a function that takes the user’s input and generates the actual HTML output that appears on the front end of the website.
public function render_shortcode( $atts, $content, $tag ) {
$atts = ( shortcode_atts( array(
'blockquote_cite' => '',
'quote_author' => '',
'extra_class' => '',
'element_id' => '',
), $atts) );
// Content
$content = wpb_js_remove_wpautop( $content, true );
$quote_author = esc_html( $atts['quote_author'] );
// Generate your HTML output here
$output = '<blockquote>';
$output .= $content;
if( $quote_author ) {
$output .= '<cite>' . $quote_author . '</cite>';
}
$output .= '</blockquote>';
return $output;
}Element parameters and options
WPBakery gives you lots of options for configuring how your element behaves and what fields it shows to users.
Key parameters
base – The shortcode tag that WordPress will use internally.
name – The display name that appears in the WPBakery interface.
category – Which category your element appears in (Content, Social, etc.).
description – Help text that explains what your element does.
params – An array of fields that users can configure.
icon – The icon that represents your element in the interface.
weight – Controls the order elements appear in the list.
Field types
WPBakery supports many different field types for your element parameters:
textfield – Basic text input textarea – Multi-line text area dropdown – Select from predefined options checkbox – True/false option colorpicker – Color selection tool attach_image – Single image selector attach_images – Multiple image selector vc_link – Link picker with URL and target options
Advanced customization options
For more complex elements, you can add custom CSS and JavaScript files that load only when your element is being used.
admin_enqueue_css/js – Files that load in the WPBakery editor front_enqueue_css/js – Files that load on the public-facing website
You can also group parameters into tabs to keep the interface organized when you have lots of options.
Best practices for custom elements
Keep it simple – Start with basic functionality and add complexity gradually.
Use clear naming – Make sure your parameter names and descriptions are easy to understand.
Test thoroughly – Check how your element behaves in different themes and page layouts.
Document your code – Add comments explaining what each part does, especially if others might work with your code later.
The truth is that most people avoid creating custom WPBakery elements because they think it requires advanced coding skills. But once you understand the basic structure, it’s really just a matter of following the pattern and customizing it for your specific needs.
Creating custom elements opens up a lot of possibilities for unique website functionality. You can build everything from custom content blocks to complex interactive features, all with the familiar WPBakery drag-and-drop interface that your clients already know how to use.
