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

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.

Instant access to 390+ Bricks code tutorials with BricksLabs Pro

9 comments

  • Francois Gonin

    Hi Maxime
    Thanks for this Tutorial. Wow, this opens up a whole new world.
    Is there maybe a quick way to add the custom setting to all elements? (or a bunch of elements)
    Thanks, François

  • Amanda Lucas

    Thanks for this Maxime, this is next level good

  • Jarno Uusi-Maahi

    Wow. Who would have thought. Thanks!

    I guess it's not possible to make the field accept dynamic data?

  • Juergen

    A big thanks from me too, Stephen, I'm new to Bricks and your posts helps me a lot to get the whole picture of how extending the builder.

  • Wilky Reyes

    Another big tutorial. Thank you Maxime!

  • Stephen

    Maxime!

    Thank you for your contribution! Seriously great post! Appreciate your voice in the Bricks community.

Leave your comment