Building Custom Blocks Programmatically with Block Lab

With v1.5 of Block Lab, we released a feature that’s easy to miss unless you know what to look for. It’s not visible in the Block Lab UI, but is something, behind the scenes, you can work with when developing with Block Lab.

You can now programmatically add and configure blocks.

The use case for this is when developers want to bundle their custom blocks with a theme or a plugin so that:

  • You just need to install the plugin or theme to get all the blocks
  • The custom blocks aren’t exposed to WP admin meddling

This is a feature that a lot of our users who are building daily with Block Lab have been asking for.

In this post, I’m going to walk you through how to use it.

Understanding the API

The Block Lab PHP API lets you write some code using a few defined functions that will pass data to the Block Lab plugin. This data represents all that is needed to register a block.

There are two different ways you can structure your code. You can have a single large nested array which contains everything for the block. Or you can separate the code out into the block and field components. We’ll look at both.

Approach 1

Let’s use an example. We’re going to make a custom Dr Seuss block based on the beloved classic One Fish, Two Fish, Red Fish, Blue Fish. My kids are so proud!

Here’s the full block of code. Have a close look and then we’ll go through it piece by piece.

function thelab_register_dr_seuss_block() {
            'title'    => 'One Fish',
            'category' => 'common',
            'icon'     => 'waves',
            'excluded' => array( 'post' ),
            'keywords' => array( 'sad', 'glad', 'bad' ),
            'fields'   => array(
                'thin' => array(
                    'label'   => 'Thin',
                    'control' => 'toggle',
                    'width'   => '25',
                    'default' => true,
                'fat' => array(
                    'label'   => 'Fat',
                    'control' => 'toggle',
                    'width'   => '25',
                    'default' => false,
                'hat'  => array(
                    'label'   => 'Hat',
                    'control' => 'select',
                    'width'   => '50',
                    'options' => array(
                            'label' => 'Yellow',
                            'value' => 'yellow',
                            'label' => 'Red',
                            'value' => 'red',
                            'label' => 'Blue',
                            'value' => 'blue',

add_action( 'block_lab_add_blocks', 'thelab_register_dr_seuss_block' );

This is what we’re creating here:

  • A block called “One Fish”
  • Giving it a category, icon, tags and excluding it from being available on Posts (so just available on pages and other CPTs)
  • Giving it 3 fields, 2 toggles, and a select

If you’re somewhat familiar with Arrays and PHP, the structure above is nice and logical.

  • We create a function called the lab_register_dr_seuss_block
  • We use the action block_lab_add_block to add our block
  • The one-fish parameter is the slug for the block
  • The first array (moving down through the code) is the block level configurations
  • The fields array is where we start adding our fields
  • Each of the following arrays (thin,fat, and hat) and their values represent fields we are adding to the block and their settings
  • We hook our thelab_register_dr_seuss_block function on the block_lab_add_blocks action.

If we jump into WordPress now and create a new page, we’ll see that this block is ready and waiting for us. πŸŽ‰

Our custom block in the Block Selector
Our custom block added to the page with the form active.

Now you can go through the normal process of templating.

So that’s a pretty big block of code and does everything all in one go. It’s nice and clear, however, you may want to shorten it up a bit. The second method allows this by separating the registering of the block from the blocks fields. We can also rely on the defaults that Block Lab offers to handle a number of things for us. This way we don’t have to explicitly define them.

Approach 2

Here’s our streamlined block of code. Different field types in this one, but it gives you a good idea of how you can shorthand this.

function thelab_register_other_dr_seuss_block() {
    block_lab_add_block( 'two-fish', array( 'icon' => 'waves' ) );
    block_lab_add_field( 'two-fish', 'hello-there-ned-how-do-you-do' );
    block_lab_add_field( 'two-fish', 'tell-me-tell-me-what-is-new', array( 'placeholder' => 'My hat is old, my teeth are gold.' ) );

add_action( 'block_lab_add_blocks', 'thelab_register_other_dr_seuss_block' );

In our thelab_register_other_dr_seuss_block we are:

  • Registering the block first with the block_lab_add_block function and setting a slug, block name (the plugin cleverly abstracts this from the slug), and an icon
  • Registering 2 fields with the block_lab_add_field function and setting a slug, help text, and placeholder
  • When registering the fields, assigning them to the two-fish block

Heading over to the WordPress admin, we can see the block is good to go and ready for templating:

Things to know

  1. With all the different field types, the configuration options between them vary quite a bit. These options are defined on the Docs pages for each field type. So if you are adding, for example, a select field programmatically, you can go to the select field docs to see the API options (controls) available to you.
  2. Blocks registered programmatically don’t appear in the WordPress admin Block Lab>All Blocks screen.
  3. If you ever register a block or field without giving it a name, a name will be auto-magically generated from the slug by removing dashes and capitalising words. Nifty!

That’s all for this one! It’s a big feature for the plugin and one we are very proud of!

Until next time, happy block building.


      1. On second thought, I’m not sure it makes sense inside of Block Lab. Maybe in a separate plugin? Block Lab is focused on creating individual blocks, but a sidebar would be consistent for every post.

        1. But it is still about Gutenberg, its controls, components and the future of WP post edit screen.
          I wonder why almost nobody (ACF,, Carbon Fields, etc.) saw the need for those panels when they are real replacement for meta boxes to store post meta data nowadays.
          Or post meta is deprecated? I don’t think so. πŸ˜‰

          Anyway, thank you for your answer.

  1. Hi,
    Thanks for creating such a wonderful plugin.
    Do we register this block_lab_add_blocks action into functions.php or is there a way we could register by putting a file inside blocks template folder for example blocks/{name}/register.php which would make it modular to copy into different sites?

    1. My suggestion is to put it in your theme under blocks/register.php, and then include the register.php file from your functions.php.

      Block Lab doesn’t try to auto-include any PHP files right now.

Leave a Reply

Your email address will not be published. Required fields are marked *