Components - InnerBlocks

Last modified: April 22 2024.

Inner blocks allow you to insert additional blocks to your blocks. Under the hood, Blockstudio is using the InnerBlocks component. Please note that it is only possible to use one InnerBlocks component per block, this is a WordPress limitation.

Basic usage

To use InnerBlocks, you need to add the InnerBlocks component to your block.

index.php


            <InnerBlocks /> or
    <InnerBlocks/>Copy

The composition is up to you. You can nest the InnerBlocks component as deep as you want or just use it by itself.

Properties

allowedBlocks

The allowedBlocks prop allows you to define which blocks can be inserted into the InnerBlocks component.

index.php

index.twig


          <InnerBlocks allowedBlocks="<?php echo esc_attr(wp_json_encode(['core/heading', 'core/paragraph'])); ?>" />Copy


          <InnerBlocks allowedBlocks="{{ ['core/heading', 'core/paragraph']|json_encode|escape('html_attr') }}" />Copy

tag

By default, the InnerBlocks component is rendered as a div element. You can change this by using the tag prop.

index.php


            <InnerBlocks tag="section" />Copy

template

The template prop allows you to define a template for the InnerBlocks component.

index.php

index.twig


          <InnerBlocks template="<?php echo esc_attr( wp_json_encode([['core/heading', ['placeholder' => 'Book Title']], ['core/paragraph', ['placeholder' => 'Summary']]])); ?>" />Copy


          <InnerBlocks template="{{ [['core/heading', { placeholder: 'Book Title' }], ['core/paragraph', { placeholder: 'Summary' }]]|json_encode|escape('html_attr') }}" />Copy

templateLock

The templateLock prop allows you to define if the template can be modified or not.

contentOnly: prevents all operations. Additionally, the block types that don't have content are hidden from the list view and can't gain focus within the block list. Unlike the other lock types, this is not overrideable by children.
all: prevents all operations. It is not possible to insert new blocks. Move existing blocks or delete them.
insert: prevents inserting or removing blocks, but allows moving existing ones.
false: prevents locking from being applied to an InnerBlocks area even if a parent block contains locking.

renderAppender

The renderAppender prop allows you to define the block appender type.

default: display the default block appender, typically the paragraph style appender when the paragraph block is allowed.
button: display a + icon button as the appender.

useBlockProps

useBlockProps will remove the outer wrapper of the InnerBlocks component inside the editor. See useBlockProps for more information.

Context

Registering

Blockstudio supports context for the InnerBlocks component. This allows you to pass data from the parent block to the child blocks. While it uses the WordPress core context mechanism under the hood, Blockstudio provides a more convenient API.

Instead of having to define all attributes that should be passed in the context separately, you can simply subscribe to all attributes of a parent block.

Let's say you have a container block setup like so:

block.json


            {
      "$schema": "https://app.blockstudio.dev/schema",
      "name": "blockstudio/container",
      "title": "Container",
      "category": "design",
      "icon": "star-filled",
      "description": "Container block.",
      "blockstudio": {
        "attributes": [
          {
            "id": "full-width",
            "type": "toggle",
            "label": "Makes section full width"
          }
        ]
      }
    }

      Copy

Inside your child block, simply use the usesContext property with the parent block name to gain access to all parent attributes in your block template.

block.json


            {
      "$schema": "https://app.blockstudio.dev/schema",
      "name": "blockstudio/element",
      "title": "Element",
      "category": "design",
      "icon": "star-filled",
      "description": "Element block.",
      "usesContext": ["blockstudio/container"],
      "parent": ["blockstudio/container"],
      "blockstudio": true
    }

      Copy

Templates

The $context and $c variables are available inside your block templates to access all parent attributes. Child blocks will automatically reload in the editor if parent data changes.

index.php

index.twig


          <?php $container = $context['blockstudio/container']; ?>

  <h1>
    <?php echo $container['full-width']
        ? 'is full width'
        : 'no full width'; ?>
  </h1>Copy


          {% set container = context['blockstudio/container'] %}

  <h1>
    {{ container['full-width']
        ? 'is full width'
        : 'no full width' }}
  </h1>Copy

Frontend wrapper

InnerBlocks has to render a wrapper element around its children inside the editor, however, it can be removed from the frontend by using blockstudio/blocks/components/innerblocks/frontend/wrap filter.

functions.php


            add_filter('blockstudio/blocks/components/innerblocks/frontend/wrap', function ($render, $block) {
      if ($block->name === 'blockstudio/my-block') {
        $render = false;
      }

      return $render;
    }, 10, 2);

      Copy

Return early

If you want to return early from the render method of your block, you can check if the $innerBlocks (it contains the <InnerBlocks/> content) variable is empty. This comes in handy if you don't want to render anything if there are no inner blocks.

index.php


            <?php if (strip_tags($innerBlocks) === '') {
      return;
    } ?>
    <InnerBlocks tag="section" />Copy

Since <InnerBlocks/> is will always render an empty paragraph tag, you can use the strip_tags function to check if the content is empty.

Dynamic templates

The Select and Radio field types support dynamically generating the InnerBlocks template depending on the field value. This is useful if you want to allow the user to select a different template for the InnerBlocks component.

index.php


            <InnerBlocks tag="section" />Copy

To do so, simply add a innerBlocks key to the options array with the template.

block.json


            {
      "$schema": "https://app.blockstudio.dev/schema",
      "name": "blockstudio/type-select-innerblocks",
      "title": "Native Select InnerBlocks",
      "category": "blockstudio-test-native",
      "icon": "star-filled",
      "description": "Native Blockstudio Select InnerBlocks block.",
      "blockstudio": {
        "attributes": [
          {
            "id": "layout",
            "type": "select",
            "label": "Layout",
            "options": [
              {
                "value": "1",
                "label": "One",
                "innerBlocks": [
                  {
                    "name": "core/columns",
                    "innerBlocks": [
                      {
                        "name": "core/column",
                        "innerBlocks": [
                          {
                            "name": "core/heading",
                            "attributes": {
                              "content": "This is the left Heading.",
                              "level": 1
                            }
                          },
                          {
                            "name": "core/paragraph",
                            "attributes": {
                              "content": "This is the left Paragraph."
                            }
                          }
                        ]
                      },
                      {
                        "name": "core/column",
                        "innerBlocks": [
                          {
                            "name": "core/heading",
                            "attributes": {
                              "content": "This is the right Heading.",
                              "level": 1
                            }
                          },
                          {
                            "name": "core/paragraph",
                            "attributes": {
                              "content": "This is the right Paragraph."
                            }
                          }
                        ]
                      }
                    ]
                  }
                ]
              },
              {
                "value": "2",
                "label": "Two",
                "innerBlocks": [
                  {
                    "name": "core/columns",
                    "innerBlocks": [
                      {
                        "name": "core/column",
                        "innerBlocks": [
                          {
                            "name": "core/heading",
                            "attributes": {
                              "content": "This is the left Heading.",
                              "level": 2
                            }
                          },
                          {
                            "name": "core/paragraph",
                            "attributes": {
                              "content": "This is the left Paragraph."
                            }
                          }
                        ]
                      },
                      {
                        "name": "core/column",
                        "innerBlocks": [
                          {
                            "name": "core/heading",
                            "attributes": {
                              "content": "This is the right Heading.",
                              "level": 2
                            }
                          },
                          {
                            "name": "core/paragraph",
                            "attributes": {
                              "content": "This is the right Paragraph."
                            }
                          }
                        ]
                      }
                    ]
                  }
                ]
              }
            ],
            "allowNull": "Select an option"
          }
        ]
      }
    }

      Copy