Skip to main content
Custom modules allow you to extend Beaver Builder with your own content elements. This guide walks through the complete module creation workflow.

​
Prerequisites

Before creating a module, ensure you have:
  • A WordPress site with Beaver Builder installed
  • A custom plugin or child theme for your code
  • Basic knowledge of PHP, HTML, and CSS
  • Access to your site’s file system

​
Module Creation Workflow

1

Create Module Directory

Create a folder for your module in your plugin or theme:
wp-content/plugins/my-plugin/modules/my-module/
The folder name should be lowercase with hyphens and will become your module’s slug.
2

Create Main Module File

Create my-module.php in your module directory:
my-module/my-module.php
<?php
/**
 * @class MyModuleClass
 */
class MyModuleClass extends FLBuilderModule {

    public function __construct() {
        parent::__construct(array(
            'name'            => __( 'My Module', 'my-plugin' ),
            'description'     => __( 'A custom module description.', 'my-plugin' ),
            'category'        => __( 'Basic', 'my-plugin' ),
            'icon'            => 'button.svg',
            'partial_refresh' => true,
        ));
    }
}
The class name should be unique and follow WordPress naming conventions. Use PascalCase with a descriptive suffix like Module or Class.
3

Register Module Settings

Add the module registration and settings form at the end of your main file:
my-module/my-module.php
FLBuilder::register_module('MyModuleClass', array(
    'general' => array(
        'title'    => __( 'General', 'my-plugin' ),
        'sections' => array(
            'general' => array(
                'title'  => '',
                'fields' => array(
                    'text' => array(
                        'type'    => 'text',
                        'label'   => __( 'Text', 'my-plugin' ),
                        'default' => __( 'Default text', 'my-plugin' ),
                    ),
                ),
            ),
        ),
    ),
));
4

Create Frontend Template

Create includes/frontend.php to render your module:
my-module/includes/frontend.php
<?php
// Access module settings via $settings variable
?>
<div class="my-module-wrapper">
    <p><?php echo esc_html( $settings->text ); ?></p>
</div>
The $settings variable is automatically available and contains all module settings. Always sanitize output appropriately.
5

Create CSS Template

Create includes/frontend.css.php for dynamic styles:
my-module/includes/frontend.css.php
<?php
// $id contains the module's unique node ID
// $settings contains module settings
?>
.fl-node-<?php echo $id; ?> .my-module-wrapper {
    padding: 20px;
}
6

Register Your Module

In your plugin’s main file, register the module with Beaver Builder:
my-plugin.php
function my_plugin_load_modules() {
    if ( class_exists( 'FLBuilder' ) ) {
        require_once 'modules/my-module/my-module.php';
    }
}
add_action( 'init', 'my_plugin_load_modules' );
7

Test Your Module

  1. Clear your WordPress cache
  2. Open the Beaver Builder editor
  3. Look for your module in the modules panel
  4. Drag it onto the page and test its functionality

​
Complete Example

Here’s a minimal working module: 
<?php
class SimpleButtonModule extends FLBuilderModule {
    public function __construct() {
        parent::__construct(array(
            'name'        => __( 'Simple Button', 'my-plugin' ),
            'description' => __( 'A simple call to action button.', 'my-plugin' ),
            'category'    => __( 'Basic', 'my-plugin' ),
            'icon'        => 'button.svg',
        ));
    }
}

FLBuilder::register_module('SimpleButtonModule', array(
    'general' => array(
        'title'    => __( 'General', 'my-plugin' ),
        'sections' => array(
            'general' => array(
                'title'  => '',
                'fields' => array(
                    'text' => array(
                        'type'    => 'text',
                        'label'   => __( 'Button Text', 'my-plugin' ),
                        'default' => __( 'Click Here', 'my-plugin' ),
                    ),
                    'link' => array(
                        'type'        => 'link',
                        'label'       => __( 'Link', 'my-plugin' ),
                        'show_target' => true,
                    ),
                ),
            ),
        ),
    ),
));

​
Module Registration

Load your module in your plugin’s main file:
my-plugin.php
<?php
/**
 * Plugin Name: My Custom Modules
 * Description: Custom Beaver Builder modules
 */

function my_plugin_load_modules() {
    if ( class_exists( 'FLBuilder' ) ) {
        // Load individual modules
        require_once plugin_dir_path( __FILE__ ) . 'modules/button-simple/button-simple.php';
    }
}
add_action( 'init', 'my_plugin_load_modules' );

​
Common Issues

  • Verify your plugin is activated
  • Check that the module class extends FLBuilderModule
  • Ensure FLBuilder::register_module() is called
  • Clear WordPress and Beaver Builder caches
  • Check for PHP errors in debug log
  • Verify field names match what you’re accessing in templates
  • Check that the settings array is properly structured
  • Ensure default values are set for required fields
  • Look for JavaScript errors in browser console
  • Verify frontend.css.php is in the includes/ directory
  • Check that you’re using the correct $id variable for selectors
  • Clear browser cache and regenerate CSS
  • Ensure CSS specificity is high enough

​
Next Steps

Module Structure

Learn about module file organization and required files

Frontend Rendering

Discover how to render module output and dynamic CSS

Settings Forms

Explore available field types and form configuration

Module API

Reference the complete module API documentation

​
Best Practices

  • Use unique class names to avoid conflicts with other modules
  • Sanitize and escape all output for security
  • Provide sensible defaults for all settings
  • Support responsive design with responsive field types
  • Test thoroughly across different themes and page layouts
  • Follow WordPress coding standards for consistency
  • Document your code to help future maintainers
  • Use translation functions for all user-facing text

​
Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us