Skip to main content
Modules are the building blocks of Beaver Builder layouts. They’re self-contained components that can be dragged into columns to add functionality like headings, buttons, images, forms, and more.

​
What Are Modules?

A module is a PHP class that extends FLBuilderModule and provides:
  • Settings Form - User interface for configuration
  • Frontend Output - HTML template for display
  • CSS Styling - Module-specific styles
  • JavaScript - Optional frontend behavior
  • Backend Logic - Data processing and validation
Modules live in the modules/ directory and follow a specific file structure for organization.

​
Module Categories

Beaver Builder includes 42+ built-in modules organized into categories:

​
Basic Modules

Everyday content elements:

Heading

Page titles and headings with custom typography

Photo

Single images with linking and effects

Button

Call-to-action buttons with icons

Rich Text

WordPress editor with full formatting

Video

YouTube, Vimeo, or self-hosted videos

Audio

Audio players for MP3 files

Icon

Font icons with customization

Separator

Visual content dividers

HTML

Custom HTML/JavaScript code

​
Advanced Modules

Complex interactive components:

Gallery

Photo galleries with lightbox

Slideshow

Image slideshows with transitions

Slider

Content sliders with multiple slides

Accordion

Collapsible content sections

Tabs

Tabbed content interface

Contact Form

Customizable contact forms

Subscribe Form

Email subscription forms

Login Form

WordPress login interface

Search

Site search functionality

​
Content Modules

Callout

Promotional callout boxes

CTA

Call-to-action sections

Pricing Table

Product pricing displays

Testimonials

Customer testimonials slider

Numbers

Animated number counters

Star Rating

Visual rating display

Icon Group

Multiple icons in a row

Button Group

Multiple buttons together

List

Styled lists with icons

​
Post Modules

Post Grid

Blog post grid layouts

Post Carousel

Rotating post carousel

Post Slider

Post content slider

​
WordPress Modules

Menu

WordPress navigation menus

Sidebar

WordPress sidebar areas

Widget

Any WordPress widget

Social Buttons

Social media sharing

​
Additional Modules

Map

Google Maps integration

Countdown

Event countdown timer

Box

Container with background

WooCommerce

eCommerce integration

BigCommerce

BigCommerce products

​
Complete Module List

Here’s the full list of 42+ modules available:
Basic: Heading, Photo, Button, Rich Text, Video, Audio, Icon, Separator, HTMLAdvanced: Gallery, Slideshow, Content Slider, Accordion, Tabs, Contact Form, Subscribe Form, Login Form, Search, MenuContent: Callout, CTA, Pricing Table, Testimonials, Numbers, Star Rating, Icon Group, Button Group, ListPost: Post Grid, Post Carousel, Post SliderWordPress: Sidebar, Widget, Social ButtonsOther: Map, Countdown, Box, WooCommerce, BigCommerce, ACF Block, Reusable Block, North Commerce

​
Module Lifecycle

Understanding the module lifecycle helps you know when to hook into different events:
1

Registration

Module class is instantiated and registered via FLBuilder::register_module()
FLBuilder::register_module('FLHeadingModule', $form_settings);
2

Settings Loaded

When editing, module settings are loaded and defaults merged
public function filter_settings($settings, $helper) {
    // Handle backwards compatibility
    return $settings;
}
3

Settings Saved

User submits settings form, update() method processes data
public function update($settings) {
    // Sanitize settings
    $settings->text = wp_kses_post($settings->text);
    return $settings;
}
4

Frontend Render

Module HTML is generated from PHP template file
// includes/frontend.php
<div class="fl-module-heading">
    <<?php echo $settings->tag; ?>><?php echo $settings->heading; ?></<?php echo $settings->tag; ?>>
</div>
5

CSS Generated

Module CSS is compiled from frontend.css.php and cached
6

JS Executed

Module JavaScript runs on page load if frontend.js exists
7

Module Deleted

When removed, delete() method cleans up resources
public function delete() {
    // Delete cached photos, etc.
}

​
Creating a Custom Module

​
Basic Module Structure

<?php
/**
 * @class MyCustomModule
 */
class MyCustomModule extends FLBuilderModule {
    
    /**
     * Constructor
     */
    public function __construct() {
        parent::__construct(array(
            'name'            => __('My Custom Module', 'my-plugin'),
            'description'     => __('A custom module example', 'my-plugin'),
            'category'        => __('Basic', 'my-plugin'),
            'icon'            => 'text.svg',
            'partial_refresh' => true,
        ));
    }
    
    /**
     * Enqueue scripts and styles
     */
    public function enqueue_scripts() {
        $this->add_css('my-custom-css', $this->url . 'css/frontend.css');
        $this->add_js('my-custom-js', $this->url . 'js/frontend.js', array('jquery'));
    }
}

// Register the module
FLBuilder::register_module('MyCustomModule', array(
    'general' => array(
        'title'    => __('General', 'my-plugin'),
        'sections' => array(
            'general' => array(
                'title'  => '',
                'fields' => array(
                    'text' => array(
                        'type'    => 'text',
                        'label'   => __('Text', 'my-plugin'),
                        'default' => 'Hello World',
                    ),
                ),
            ),
        ),
    ),
));

​
Directory Structure

my-module/
├── my-module.php          # Module class
├── icon.svg               # Module icon
├── includes/
│   ├── frontend.php       # HTML template
│   └── frontend.css.php   # Dynamic CSS (optional)
├── css/
│   └── frontend.css       # Static CSS
└── js/
    └── frontend.js        # Frontend JavaScript

​
Module Settings Form

The settings form defines the UI for module configuration: 
array(
    'general' => array(
        'title'    => __('General', 'my-plugin'),
        'sections' => array(
            'content' => array(
                'title'  => __('Content', 'my-plugin'),
                'fields' => array(
                    'heading' => array(
                        'type'    => 'text',
                        'label'   => __('Heading', 'my-plugin'),
                        'default' => 'My Heading',
                        'preview' => array(
                            'type'     => 'text',
                            'selector' => '.my-heading',
                        ),
                    ),
                    'photo' => array(
                        'type'  => 'photo',
                        'label' => __('Photo', 'my-plugin'),
                    ),
                    'color' => array(
                        'type'       => 'color',
                        'label'      => __('Color', 'my-plugin'),
                        'default'    => '333333',
                        'show_reset' => true,
                        'show_alpha' => true,
                        'preview'    => array(
                            'type'     => 'css',
                            'selector' => '.my-heading',
                            'property' => 'color',
                        ),
                    ),
                ),
            ),
        ),
    ),
    'style' => array(
        'title'    => __('Style', 'my-plugin'),
        'sections' => array(
            'colors' => array(
                'title'  => __('Colors', 'my-plugin'),
                'fields' => array(
                    'bg_color' => array(
                        'type'  => 'color',
                        'label' => __('Background', 'my-plugin'),
                    ),
                ),
            ),
        ),
    ),
)

​
Available Field Types

  • text - Single line text input
  • textarea - Multi-line text area
  • editor - WordPress rich text editor
  • code - Code editor with syntax highlighting

​
Advanced Module Features

​
Partial Refresh

Enable live preview without page reload: 
public function __construct() {
    parent::__construct(array(
        'name'            => __('My Module', 'my-plugin'),
        'partial_refresh' => true, // Enable live preview
    ));
}

​
Container Modules

Modules that accept child modules: 
public $accepts = array('my-child-module'); // Accept specific children
// OR
public $accepts = 'all'; // Accept any module

​
Module Dependencies

Declare dependencies between modules:
modules/class-fl-builder.php:174
$deps = array(
    'post-carousel' => array(
        'post-grid',
        'photo',
    ),
    'callout' => array(
        'button',
        'photo',
        'icon',
    ),
);
When a module has dependencies, the dependent modules must be enabled for the parent module to function properly.

​
Best Practices

public function update($settings) {
    $settings->text = wp_kses_post($settings->text);
    $settings->url  = esc_url($settings->url);
    return $settings;
}

<h2><?php echo esc_html($settings->heading); ?></h2>
<a href="<?php echo esc_url($settings->link); ?>">Link</a>
<img src="<?php echo esc_url($settings->photo_src); ?>" />

wp_nonce_field('my_module_action', 'my_module_nonce');

public function enqueue_scripts() {
    if (FLBuilderModel::is_builder_active()) {
        // Builder preview scripts
    } else {
        // Frontend scripts only
        $this->add_js('frontend', $this->url . 'js/frontend.js');
    }
}

​
Next Steps

Module Developer Guide

Complete guide to building custom modules

Settings Forms

Learn about all available field types

Available Modules

Complete list of built-in modules

API Reference

FLBuilderModule class reference

Build docs developers (and LLMs) love

Get started for freeTalk to us