How to Add a Custom Control Field to an Element in Bricks

In this tutorial, we’ll learn how to add a custom control field to an element and dynamically change a CSS property inside the builder.

Table of Contents

• Introduction
• Element List
• Control Types
• The code
• The result

Introduction

In my opinion, one of the most underrated filters in Bricks is bricks/elements/{element_name}/controls. With it, you can literally add any control to any existing element and fill all the gaps when you need CSS properties that aren’t integrated inside the builder.

One of the CSS properties that I badly need when building my sites in Bricks is the aspect-ratio property on images. Unfortunately, there is no core control for it. No problem let’s build it!

Element List

Here is the full list of elements you can customize in Bricks:

// Layout
'container',
'section', // @since 1.5
'block', // @since 1.5
'div', // @since 1.5

// Basic
'heading',
'text-basic', // @since 1.3.6
'text',
'button',
'icon',
'image',
'video',

// General
'divider',
'icon-box',
'social-icons', // @since 1.4 (Label: Icon List)
'list',
'accordion',
'accordion-nested',
'tabs',
'tabs-nested', // @since 1.5
'form',
'map',
'alert',
'animated-typing',
'countdown',
'counter',
'pricing-tables',
'progress-bar',
'pie-chart',
'team-members',
'testimonials',
'html',
'code',
'template',
'logo',
'facebook-page',

// Media
'image-gallery',
'audio',
'carousel',
'slider',
'slider-nested',
'svg',

// WordPress
'wordpress',
'posts',
'pagination',
'nav-menu',
'sidebar',
'search',
'shortcode',

// Single
'post-title',
'post-excerpt',
'post-meta',
'post-content',
'post-sharing',
'related-posts',
'post-author',
'post-comments',
'post-taxonomy',
'post-navigation',

To target the element that we want to change, we just have to replace {element_name} with one of the names listed above in the following function: add_filter( 'bricks/elements/{element_name}/controls', function( $controls ) {}

So since our goal is to add a new control to the image element, our filter will be: add_filter( 'bricks/elements/image/controls', function( $controls ) {}.

Control Types

There are 34 different control fields in Bricks: from a basic number control to date-picker controls or slider controls. You can find the full control list here: https://academy.bricksbuilder.io/article/element-controls/. To learn more about the specificities of each control, click on any of the labels inside the table.

In our example, we will use a number control.

The code

I’ll try to break down the basics of this filter by commenting on top of each line.

Add the following code to your functions.php file or inside your code snippets plugin:

//change the {element_name} to the element you want to target
add_filter( 'bricks/elements/image/controls', function( $controls ) {
  // Set a name to the new control field - this has no impact on the builder experience
  $controls['aspectRatio'] = [
      // Tab under which to show the control. Accepts: content or style.
      'tab'      => 'content',
      // Set the label that will show up in the builder
      'label'    => esc_html__( 'Aspect Ratio', 'bricks' ),
      // Choose a type of field
      'type'     => 'number',
      // Set your CSS property and Selector
      'css'         => [
        [
          // the CSS property you want to add
          'property' => 'aspect-ratio',
          // the CSS selector where the property should be applied - blank targets the root of the element
          'selector' => '',
        ],
        // You can target multiple selectors at once. Now we'll target the img tag
        [
          'property' => 'aspect-ratio',
          'selector' => 'img',
        ],
      ],
      // Set false for unitless
      'units' => false,
      // Set the increasing/decreasing value
      'step' => '0.01',
      // Set the default control value.
      'default' => 1,
      // Set to true to show control label and input on the same line.
      'inline' => false,
  ];

  return $controls;
} );

The result

Now let’s refresh the builder and we’ll see our new Aspect Ratio control inside the content tab of the image element:

Congrats! You just created your first custom control in Bricks!

The user-entered value in the control field can be retrieve for use in the element’s output via

$element->settings["aspectRatio"]

inside the bricks/element/settings filter’s function.