How to Build a Gutenberg Block with a Toolbar Control

In this tutorial, we will learn how to add an alignment control to the toolbar of a Gutenberg block.

This tutorial builds off the How to Build Gutenberg Blocks Using JSX tutorial. If you’re not familiar with Gutenberg or JSX, I would suggest starting with that tutorial.

The code from this tutorial is available as a fully functioning plugin. Check out the example on Github.

PHP

The main plugin PHP file simply defines the plugin details and loads our Javascript file. It doesn’t have any significant differences from the How to Build Gutenberg Blocks Using JSX example.

Javascript

All the Javascript for our plugin will be placed in the js/block.js file and will be compiled to the js.block.build.js file. Okay, let’s dive into the code.

Load dependencies

The first thing we need to do is load the dependencies we will be using in this block.

const { __ } = wp.i18n;
const {
	registerBlockType,
	BlockControls,
	AlignmentToolbar
} = wp.blocks;

There are four things we’re loading here:

• __ – This is used for setting up translation. We pass any text strings we’re using in this file through this function to allow for the strings to be translated before being displayed.
• registerBlockType – We need this to register our new block.
• BlockControls – This is the wrapper for any toolbar controls we want to add.
• AlignmentToolbar – This is the control we’ll be adding to the block control toolbar.

Register block settings

Next, we need to register our block and define its settings:

registerBlockType( 'mdlr/toolbar-control-jsx-example', {
	title: __( 'Toolbar Control Example with JSX' ),
	icon: 'admin-tools',
	category: 'common',
	attributes: {
		alignment: {
			type: 'string',
		},
	},

Here we register our block with a custom namespace and a number of settings. The only new setting is the attributes setting. We will be using this setting to keep track of the text alignment for this block.

Block edit function

Now that we’ve loaded our dependencies and defined our settings, we can get into the meat of our code. The edit function is what defines how the block functions within the Gutenberg editor.

	edit( { attributes, className, focus, setAttributes } ) {

Our edit function is pulling in four attributes:

• attributes – This is the list of attributes (in our case, just a single attribute). It holds the alignment attribute we defined above.
• className This is the auto-generated class name for our block.
• focus – This holds the focus state for our block.
• setAttributes – This allows us to easily update our attribute values (in this case, the text alignment of our block).

Next we set up our alignment attribute so we can use it directly, instead of having to always reference it within the attributes object:

const { alignment } = attributes;

Then we set up a function to update the alignment attribute whenever the alignment setting is changed:

		function onChangeAlignment( updatedAlignment ) {
			setAttributes( { alignment: updatedAlignment } );
		}

The following section actually adds the block and its toolbar to the editor:

		return (
			<div className={ className }>
				{
					!! focus && (
						<BlockControls>
							<AlignmentToolbar
								value={ alignment }
								onChange={ onChangeAlignment }
							/>
						</BlockControls>
					)
				}
				<p style={ {textAlign:  alignment } }>Toolbar control block example built with JSX.</p>
			</div>
		);
	},

You’ll notice that we start with a div that uses the className we passed in at the beginning of the edit function. Then we check to see if our block has the focus of the editor, and if it does, we display the block controls with our alignment control inside. Our alignment control has two attributes:

• value – The value hold our alignment value.
• onChange – Holds the name of the function to call when the value changes.

Finally, we have the block content. The block content is the same as the static block example, with a style attribute added to implement the alignment setting controlled by the alignment toolbar.

Block save function

The save function is similar to the edit function. However, because it is responsible for displaying the block on the front end, it doesn’t need the block controls or alignment toolbar code.

	save( { attributes, className } ) {
		const { alignment } = attributes;

		return (
			<div className={ className }>
				<p style={ {textAlign:  alignment } }>Toolbar control block example built with JSX.</p>
			</div>
		);
	},

Lastly, we need to make sure we close the code we opened on the registerBlockType line:

} );

Conclusion

And that should do it! We should now have a custom Gutenberg block with an alignment toolbar that controls the text alignment of our block: