Custom Gutenberg Block Controls: Toolbars and Inspector

In our previous article, we showed you how to create your own custom Gutenberg block using PHP, CSS, and JavaScript.

In this guide, we’ll show you how to add block controls to your custom block to give you and your users more options in the editor.

The two forms of block controls in Gutenberg are the toolbar and the inspector. Both of these items can be edited in JavaScript and will subsequently appear in the editor.

Remember that these controls are editor specific, so you won’t know if your code works until you have them plugged in to Gutenberg.

PHP

The PHP file that we created in the previous article won’t change at all in this tutorial. Instead, we’ll be working completely in JavaScript to add the toolbar and inspector.

If you didn’t read it yet, go ahead and check it out. You’ll need the previous code to get your custom block set up.

JavaScript

It’s here in JavaScript where the real magic happens. We’ll be going back to our original file and adding dependencies and adding toolbar and inspector settings using registerBlockType.

The reason we use registerBlockType is because each set of controls is attached to a specific block type. For example, an image block will have different options than a paragraph block or a title block.  

Therefore, when we create a new block and register it, we’ll have to add the controls in this section.

After you decide what functionality you want your block to have, you’ll have to decide whether to place it in the toolbar or the inspector.

Toolbar

The Toolbar is the small options box that pops up when you select a Gutenberg block.

If you registered your block as a RichText component, the toolbar will automatically generate the options for Bold, Italic, and Strikethrough for your block.

However, if you didn’t register it as a RichText component, you’ll have to manually add those features in.

To edit the toolbar, you’ll use the BlockControls element.

In the following example, we’re going to try adding simple alignment options to our block. To do this, we’ll add the AlignmentToolbar function. 

var el = wp.element.createElement,
  registerBlockType = wp.blocks.registerBlockType,
  RichText = wp.editor.RichText,
  BlockControls = wp.editor.BlockControls,
  AlignmentToolbar = wp.editor.AlignmentToolbar;

registerBlockType( 'yourgutenbergblock', {
  title: 'Your Gutenberg Block',

  icon: 'dash-icon',

  category: 'layout',

  attributes: {
    content: {
      type: 'array',
      source: 'children',
      selector: 'p',
    },
    alignment: {
      type: 'string',
    },
  },
  
  edit: function( props ) {
    var content = props.attributes.content,
      alignment = props.attributes.alignment;

    function onChangeContent( newContent ) {
      props.setAttributes( { content: newContent } );
    }

    function onChangeAlignment( newAlignment ) {
      props.setAttributes( { alignment: newAlignment } );
    }

    return [
      el(
        BlockControls,
        { key: 'controls' },
        el(
          AlignmentToolbar,
          {
            value: alignment,
            onChange: onChangeAlignment
           }
        )
      ),
      el(
         RichText,
         {
           key: 'editable', 
           tagName: 'p',
           className: props.className,
           style: { textAlign: alignment },
           onChange: onChangeContent,
           value: content,
         }
       )
     ];
  }, 
  
  save: function( props ) {
    var content = props.attributes.content,
      alignment = props.attributes.alignment;
    
    return el( RichText.Content, {
      className: props.className,
      style: { textAlign: alignment },
      value: content
    } );
  },
);

Inspector

The Inspector is the column on the right side that contains various block settings.

Although the toolbar presents us with plenty of options, the inspector allows us to have greater control over block settings without taking up a ton of space on the editor page.

For this reason, it’s best that you include more advanced controls in the inspector section, rather than the toolbar.

To edit the inspector, you’ll use the InspectorControls element.

return [
      el(
        InspectorControls,
        { key: 'controls' },
        el(
          AlignmentToolbar,
          {
            value: alignment,
            onChange: onChangeAlignment
           }
        )
      ),
      el(
         RichText,
         {
           key: 'editable', 
           tagName: 'p',
           className: props.className,
           style: { textAlign: alignment },
           onChange: onChangeContent,
           value: content,
         }
       )
     ];

As you can see, all we did was replace the instance of BlockControls with InspectorControls to render controls in the inspector region. 

Summary

If you already have your JavaScript document set up, adding block controls and inspector controls to your block is actually quite simple to do.

All you have to do is go back into your JavaScript file and add these lines of code to add the toolbar and inspector functionality. 

Stay tuned for our next article in UltraBlocks’ ‘Comprehensive Guide to Gutenberg’ series.