Nested Blocks

Nested blocks add a lot of power to Gutenberg — you can create blocks, which themselves contain more blocks.

The <InnerBlocks /> component acts as a container for child blocks.

Note that you can only have ONE InnerBlocks per-block. This is a WordPress limitation.

Block Tagging#

Most of the time, we want to restrict where blocks can be used. For example, we might have a set of 'root' blocks which the user can only be added to the root of the page. Then, we might want some 'inline' blocks which can be added to some of those root blocks. We may also have specialised blocks, like a 'Button Row', which can only accept 'Button' blocks.

To do this, we've invented a 'tags' system for blocks, which is defined in the comments section of a block.

/*
 * ...
 * Tags: root
 * Child tags: inline
 */

Use 'Tags' to define the tags on this block, as a comma separated list if defining multiple tags. The 'root' tag is special, in that any block tagged with it can be added to the root of the page.

If the block has InnerBlocks, you can use Child tags to indirectly specify the allowed block types which can be added to this block.

Tagging core blocks#

You can also tag core blocks, which are blocks which are included by WordPress, using some PHP code.

Note that you can tag core blocks multiple times with multiple tags.

<?php

  ED()->tagCoreBlocks("wysiwyg", [
    "core/paragraph",
    "core/list",
    "core/heading",
  ]);

?>

Putting it all together#

For example, if you have a 'Section' block which accepts some WYSIWYG blocks like headings and paragraphs as well as a 'Button Row' block, and only want to allow 'Button' blocks to be added to the 'Button Row', you might have something like this:

/*
 * ...
 * Tags: root
 * Child tags: inline, wysiwyg
 */

/*
 * ...
 * Tags: inline
 * Child tags: buttons
 */

/*
 * ...
 * Tags: buttons
 */

  ED()->tagCoreBlocks("wysiwyg", [
    "core/paragraph",
    "core/list",
    "core/heading",
  ]);