Custom Field Types

Beaver Builder provides a powerful field system that allows you to create custom field types for your modules. Fields are rendered using JavaScript templates and handle all aspects of user input.

Field Type System

Fields in Beaver Builder are defined using configuration arrays in your module’s settings and rendered using Underscore.js templates located in includes/ui-field-*.php files.

Field Configuration Structure

'my_field' => array(
    'type'        => 'text',           // Field type
    'label'       => __( 'My Field', 'my-plugin' ),
    'default'     => '',               // Default value
    'placeholder' => '',               // Placeholder text
    'help'        => '',               // Help text
    'preview'     => array(            // Live preview settings
        'type'     => 'css',
        'selector' => '.my-selector',
        'property' => 'color'
    ),
    'connections' => array( 'string' ) // Allowed connection types
)

Available Field Types

Beaver Builder includes a comprehensive set of built-in field types:

Basic Input Fields

Text Field

Simple text input with optional character limit:

'text_field' => array(
    'type'        => 'text',
    'label'       => __( 'Text', 'my-plugin' ),
    'default'     => '',
    'maxlength'   => 100,
    'placeholder' => __( 'Enter text', 'my-plugin' ),
    'connections' => array( 'string', 'html', 'url' )
)

From class-fl-builder-ajax.php:85, text fields are commonly used for simple string inputs.

Textarea Field

Multi-line text input:

'textarea_field' => array(
    'type'        => 'textarea',
    'label'       => __( 'Description', 'my-plugin' ),
    'default'     => '',
    'rows'        => 6,
    'placeholder' => __( 'Enter description', 'my-plugin' )
)

Editor Field

WordPress TinyMCE editor:

'editor_field' => array(
    'type'        => 'editor',
    'label'       => __( 'Content', 'my-plugin' ),
    'default'     => '',
    'media_buttons' => true,
    'wpautop'     => true,
    'connections' => array( 'string', 'html' )
)

Selection Fields

Select Field

Dropdown select with single or multiple selection:

'select_field' => array(
    'type'    => 'select',
    'label'   => __( 'Choose Option', 'my-plugin' ),
    'default' => 'option-1',
    'options' => array(
        'option-1' => __( 'Option 1', 'my-plugin' ),
        'option-2' => __( 'Option 2', 'my-plugin' ),
        'group-1' => array(
            'label'   => __( 'Group 1', 'my-plugin' ),
            'options' => array(
                'option-3' => __( 'Option 3', 'my-plugin' )
            )
        )
    ),
    'toggle' => array(
        'option-1' => array(
            'fields' => array( 'related_field' )
        )
    )
)

The select field supports:

Option groups (ui-field-select.php:145-180)
Field toggling based on selection (ui-field-select.php:64)
Multi-select mode (ui-field-select.php:53)

Button Group Field

Visual button group for selection:

'button_group' => array(
    'type'    => 'button-group',
    'label'   => __( 'Layout', 'my-plugin' ),
    'default' => 'grid',
    'options' => array(
        'grid'   => __( 'Grid', 'my-plugin' ),
        'list'   => __( 'List', 'my-plugin' ),
        'slider' => __( 'Slider', 'my-plugin' )
    )
)

Media Fields

Photo Field

Image selector with size options:

'photo_field' => array(
    'type'        => 'photo',
    'label'       => __( 'Photo', 'my-plugin' ),
    'show_remove' => true,
    'connections' => array( 'photo' )
)

The photo field provides:

Media library integration (ui-field-photo.php:26-59)
Image size selection (ui-field-photo.php:99-105)
SVG support (ui-field-photo.php:80-89)
External URL support (ui-field-photo.php:19-25)

Multiple Photos Field

Multiple image selector:

'photos_field' => array(
    'type'  => 'multiple-photos',
    'label' => __( 'Gallery', 'my-plugin' )
)

Video Field

Video URL input:

'video_field' => array(
    'type'        => 'video',
    'label'       => __( 'Video', 'my-plugin' ),
    'show_remove' => true
)

Design Fields

Color Field

Color picker with opacity support:

'color_field' => array(
    'type'       => 'color',
    'label'      => __( 'Color', 'my-plugin' ),
    'default'    => 'ff0000',
    'show_reset' => true,
    'show_alpha' => true,
    'preview'    => array(
        'type'     => 'css',
        'selector' => '.my-element',
        'property' => 'color'
    )
)

The color field template (ui-field-color.php:1-27) shows:

Alpha channel support (ui-field-color.php:3)
Reset button option (ui-field-color.php:10-18)
Deferred rendering for performance (ui-field-color.php:2)

Typography Field

Complete typography control with responsive settings:

'typography_field' => array(
    'type'       => 'typography',
    'label'      => __( 'Typography', 'my-plugin' ),
    'responsive' => true,
    'preview'    => array(
        'type'     => 'css',
        'selector' => '.my-text'
    )
)

Typography includes (ui-field-typography.php:3-28):

Font family and weight
Font size with units (px, em, rem, vw, ch, %)
Line height
Letter spacing
Text alignment
Text transform
Text decoration
Font style and variant
Text shadow

Border Field

Border configuration:

'border_field' => array(
    'type'       => 'border',
    'label'      => __( 'Border', 'my-plugin' ),
    'responsive' => true,
    'preview'    => array(
        'type'     => 'css',
        'selector' => '.my-element'
    )
)

Dimension Field

Four-sided dimension control (padding, margin):

'padding_field' => array(
    'type'       => 'dimension',
    'label'      => __( 'Padding', 'my-plugin' ),
    'responsive' => true,
    'default'    => '',
    'units'      => array( 'px', 'em', '%' ),
    'preview'    => array(
        'type'     => 'css',
        'selector' => '.my-element',
        'property' => 'padding'
    )
)

Shadow Field

Box or text shadow:

'shadow_field' => array(
    'type'        => 'shadow',
    'label'       => __( 'Shadow', 'my-plugin' ),
    'show_spread' => true,
    'preview'     => array(
        'type'     => 'css',
        'selector' => '.my-element',
        'property' => 'box-shadow'
    )
)

Unit Fields

'unit_field' => array(
    'type'    => 'unit',
    'label'   => __( 'Width', 'my-plugin' ),
    'default' => '100',
    'units'   => array( 'px', '%', 'vw' ),
    'slider'  => array(
        'min'  => 0,
        'max'  => 1000,
        'step' => 10
    ),
    'responsive' => true
)

Special Fields

Link Field

Link configuration with target and nofollow:

'link_field' => array(
    'type'          => 'link',
    'label'         => __( 'Link', 'my-plugin' ),
    'show_target'   => true,
    'show_nofollow' => true,
    'connections'   => array( 'url' )
)

Icon Field

Icon picker:

'icon_field' => array(
    'type'        => 'icon',
    'label'       => __( 'Icon', 'my-plugin' ),
    'show_remove' => true
)

Suggest Field

Auto-suggest field:

'suggest_field' => array(
    'type'    => 'suggest',
    'label'   => __( 'Tags', 'my-plugin' ),
    'action'  => 'fl_as_posts',
    'data'    => 'post',
    'limit'   => 10
)

Post Type Field

Post type selector:

'post_type_field' => array(
    'type'    => 'post-type',
    'label'   => __( 'Post Type', 'my-plugin' ),
    'default' => 'post'
)

Creating Custom Field Types

To create a custom field type, you need two components:

1. Register the Field Type

function my_custom_field_assets() {
    if ( class_exists( 'FLBuilder' ) && FLBuilder::is_builder_active() ) {
        // Enqueue field JavaScript
        wp_enqueue_script(
            'my-custom-field',
            MY_PLUGIN_URL . 'js/my-custom-field.js',
            array( 'jquery' ),
            '1.0',
            true
        );

        // Enqueue field CSS
        wp_enqueue_style(
            'my-custom-field',
            MY_PLUGIN_URL . 'css/my-custom-field.css',
            array(),
            '1.0'
        );
    }
}
add_action( 'wp_enqueue_scripts', 'my_custom_field_assets' );

2. Create Field Template

Create a template file following the pattern in ui-field-*.php:

<?php
/**
 * Custom field template
 * File: includes/ui-field-custom.php
 */
?>
<#
// JavaScript template using Underscore.js
var value = data.value ? data.value : '';
var field = data.field;
#>
<div class="fl-custom-field<# if ( field.className ) { #> {{field.className}}<# } #>">
    <input 
        type="text" 
        name="{{data.name}}" 
        value="{{value}}" 
        class="fl-custom-field-input"
        <# if ( field.placeholder ) { #>placeholder="{{field.placeholder}}"<# } #>
    />
    <button class="fl-custom-field-button" type="button">
        <?php _e( 'Custom Action', 'my-plugin' ); ?>
    </button>
</div>

3. Load Custom Template

Tell Beaver Builder to load your custom field template:

function my_load_custom_field_templates() {
    $template_path = MY_PLUGIN_DIR . 'includes/ui-field-custom.php';
    
    if ( file_exists( $template_path ) ) {
        include $template_path;
    }
}
add_action( 'fl_builder_ui_enqueue_scripts', 'my_load_custom_field_templates' );

4. Add Field JavaScript

Create the field behavior:

(function($) {
    /**
     * Custom field class
     */
    FLBuilder.registerFieldClass( 'custom', {
        
        /**
         * Initialize field
         */
        init: function() {
            var field = this;
            
            field.$el = $( field.el );
            field.$input = field.$el.find( '.fl-custom-field-input' );
            field.$button = field.$el.find( '.fl-custom-field-button' );
            
            field.$button.on( 'click', field.onButtonClick.bind( field ) );
        },
        
        /**
         * Handle button click
         */
        onButtonClick: function( e ) {
            e.preventDefault();
            
            var field = this;
            var currentValue = field.$input.val();
            
            // Custom logic
            field.$input.val( currentValue + ' modified' );
            
            // Trigger change for preview
            field.$input.trigger( 'change' );
        },
        
        /**
         * Get field value
         */
        getValue: function() {
            return this.$input.val();
        },
        
        /**
         * Set field value
         */
        setValue: function( value ) {
            this.$input.val( value );
        }
    });
    
})(jQuery);

5. Use Custom Field

'my_custom_setting' => array(
    'type'    => 'custom',
    'label'   => __( 'Custom Field', 'my-plugin' ),
    'default' => '',
    'preview' => array(
        'type'     => 'css',
        'selector' => '.my-element',
        'property' => 'content'
    )
)

Field Rendering Process

Understanding how fields are rendered helps when creating custom fields:

Template Loading

Field templates are loaded from includes/ui-field-*.php when the settings panel opens.

Template Compilation

Underscore.js compiles templates with the data object containing:

data.name - Field name
data.value - Current value
data.field - Field configuration
data.settings - All module settings

Field Initialization

JavaScript field classes initialize after rendering (FLBuilder.registerFieldClass).

Value Binding

Field values are bound to hidden inputs that sync with the settings form.

Field Preview System

Fields can trigger live previews using the preview configuration:

'preview' => array(
    'type'     => 'css',           // 'css', 'text', 'refresh'
    'selector' => '.my-element',   // CSS selector
    'property' => 'color',         // CSS property or 'html'
    'unit'     => 'px',            // Optional unit
    'important' => true            // Add !important
)

Related to FLBuilderCSS from class-fl-builder-css.php:722-738.

Best Practices

Field Naming

Use descriptive, unique field names to avoid conflicts:

'my_plugin_unique_field'

Defaults

Always provide sensible defaults:

'default' => ''

Validation

Validate and sanitize field values:

'sanitize' => 'text'

Performance

Use deferred rendering for complex fields:

'deferRendering' => true

Module Development

Learn about creating custom modules

AJAX Operations

Handle AJAX in custom fields

CSS Generation

Generate CSS from field values

Settings API

Module settings configuration

Development

Module Development

Advanced Topics

Field Type System

Field Configuration Structure

Available Field Types

Basic Input Fields

Selection Fields

Media Fields

Design Fields

Unit Fields

Special Fields

Creating Custom Field Types

1. Register the Field Type

2. Create Field Template

3. Load Custom Template

4. Add Field JavaScript

5. Use Custom Field

Field Rendering Process

Field Preview System

Best Practices

Field Naming

Defaults

Validation

Performance

Module Development

AJAX Operations

CSS Generation

Settings API

Build docs developers (and LLMs) love

Development

Module Development

Advanced Topics

​Field Type System

​Field Configuration Structure

​Available Field Types

​Basic Input Fields

​Selection Fields

​Media Fields

​Design Fields

​Unit Fields

​Special Fields

​Creating Custom Field Types

​1. Register the Field Type

​2. Create Field Template

​3. Load Custom Template

​4. Add Field JavaScript

​5. Use Custom Field

​Field Rendering Process

​Field Preview System

​Best Practices

Field Naming

Defaults

Validation

Performance

​Related Resources

Module Development

AJAX Operations

CSS Generation

Settings API

Build docs developers (and LLMs) love

Field Type System

Field Configuration Structure

Available Field Types

Basic Input Fields

Selection Fields

Media Fields

Design Fields

Unit Fields

Special Fields

Creating Custom Field Types

1. Register the Field Type

2. Create Field Template

3. Load Custom Template

4. Add Field JavaScript

5. Use Custom Field

Field Rendering Process

Field Preview System

Best Practices

Related Resources