Introduction
Welcome to Day 23 of the Gutenberg development series! Today, we’ll focus on custom block controls, which allow you to add settings and options directly to your custom blocks. These controls can be added to the block’s sidebar or as inline controls in the block toolbar, giving users the ability to customize aspects like colors, alignment, text size, and more.
In this guide, you’ll learn how to:
- Add block controls using the InspectorControls component.
- Create inline toolbar controls for quick settings.
- Customize block attributes based on user input.
What are Custom Block Controls in Gutenberg?
Custom block controls provide users with additional options to customize the appearance and behavior of blocks. These controls can be added to:
- Inspector Controls: Sidebar settings where users can adjust block-specific options like colors, sizes, and alignment.
- Block Toolbar: Inline settings for quick access to options like alignment, boldness, or text styling.
By adding custom controls, you enhance the flexibility of your blocks, allowing users to tailor the block to their specific needs without needing to write code.
Step 1: Adding Inspector Controls for Sidebar Settings
Let’s start by adding Inspector Controls to a Testimonial Block, allowing users to adjust the text color and background color.
- Register the Block with Inspector Controls
In your block registration file (e.g., blocks/testimonial-block.js), use the InspectorControls component to add sidebar settings.
import { registerBlockType } from '@wordpress/blocks';
import { InspectorControls, ColorPalette } from '@wordpress/block-editor';
import { PanelBody, RangeControl } from '@wordpress/components';
import { __ } from '@wordpress/i18n';
registerBlockType('my-theme/testimonial-block', {
title: __('Testimonial Block'),
icon: 'format-quote',
category: 'my-custom-category',
attributes: {
content: {
type: 'string',
default: '',
},
textColor: {
type: 'string',
default: '#000000',
},
backgroundColor: {
type: 'string',
default: '#ffffff',
},
},
edit: ({ attributes, setAttributes }) => {
const { content, textColor, backgroundColor } = attributes;
return (
<>
<InspectorControls>
<PanelBody title={__('Text Settings')}>
<p>{__('Text Color')}</p>
<ColorPalette
value={textColor}
onChange={(color) => setAttributes({ textColor: color })}
/>
<p>{__('Background Color')}</p>
<ColorPalette
value={backgroundColor}
onChange={(color) => setAttributes({ backgroundColor: color })}
/>
</PanelBody>
</InspectorControls>
<textarea
value={content}
onChange={(event) => setAttributes({ content: event.target.value })}
style={{ color: textColor, backgroundColor }}
placeholder={__('Write your testimonial...')}
/>
</>
);
},
save: ({ attributes }) => {
const { content, textColor, backgroundColor } = attributes;
return (
<div style={{ color: textColor, backgroundColor }}>
<p>{content}</p>
</div>
);
},
});
Explanation:
- InspectorControls: This component allows you to add settings panels in the sidebar of the block editor.
- ColorPalette: Provides a color picker that allows users to select a text and background color.
- PanelBody: Wraps the color controls within a collapsible panel in the sidebar for better organization.
Step 2: Adding Inline Toolbar Controls
Now let’s add inline controls to the block toolbar, such as a text alignment option.
- Add Text Alignment Controls to the Block Toolbar
Update your Testimonial Block to include text alignment options in the block toolbar.
import { BlockControls, AlignmentToolbar } from '@wordpress/block-editor';
registerBlockType('my-theme/testimonial-block', {
title: __('Testimonial Block'),
icon: 'format-quote',
category: 'my-custom-category',
attributes: {
content: {
type: 'string',
default: '',
},
alignment: {
type: 'string',
default: 'left',
},
textColor: {
type: 'string',
default: '#000000',
},
backgroundColor: {
type: 'string',
default: '#ffffff',
},
},
edit: ({ attributes, setAttributes }) => {
const { content, alignment, textColor, backgroundColor } = attributes;
return (
<>
<BlockControls>
<AlignmentToolbar
value={alignment}
onChange={(newAlignment) => setAttributes({ alignment: newAlignment })}
/>
</BlockControls>
<InspectorControls>
<PanelBody title={__('Text Settings')}>
<p>{__('Text Color')}</p>
<ColorPalette
value={textColor}
onChange={(color) => setAttributes({ textColor: color })}
/>
<p>{__('Background Color')}</p>
<ColorPalette
value={backgroundColor}
onChange={(color) => setAttributes({ backgroundColor: color })}
/>
</PanelBody>
</InspectorControls>
<textarea
value={content}
onChange={(event) => setAttributes({ content: event.target.value })}
style={{ textAlign: alignment, color: textColor, backgroundColor }}
placeholder={__('Write your testimonial...')}
/>
</>
);
},
save: ({ attributes }) => {
const { content, alignment, textColor, backgroundColor } = attributes;
return (
<div style={{ textAlign: alignment, color: textColor, backgroundColor }}>
<p>{content}</p>
</div>
);
},
});
Explanation:
- BlockControls: This component allows you to add controls to the block toolbar.
- AlignmentToolbar: A pre-built component that adds text alignment options (left, center, right) to the block toolbar.
Step 3: Testing and Using Custom Block Controls
After adding custom controls, it’s important to test them in the Block Editor to ensure they work correctly.
- Rebuild the Block:
- Run your build command to ensure the block and its controls are properly registered in the Block Editor.
npm run build- Test in the Editor:
- Add the Testimonial Block to a post or page.
- Use the Text Color and Background Color options in the sidebar to change the appearance of the testimonial.
- Use the Alignment Toolbar to adjust the text alignment.
- Check the Front-End Display:
- Preview the post or page on the front end to ensure that the selected colors and alignment are applied correctly.
Best Practices for Custom Block Controls
- Organize Controls with Panels: Use PanelBody inside InspectorControls to group related settings, making it easier for users to find and adjust options.
- Use Defaults Wisely: Provide sensible default values for attributes like colors and alignment to ensure that blocks look good right out of the box.
- Test for Accessibility: Ensure that all control labels and inputs are accessible, with proper labels and descriptions for screen reader users.
Conclusion: Enhancing Blocks with Custom Controls
Adding custom block controls in Gutenberg allows you to provide users with a more powerful and flexible editing experience. Whether it’s adjusting colors, alignment, or any other block-specific setting, these controls help users customize content to their needs directly within the editor.
In this article, you’ve learned how to:
- 1. Use InspectorControls to add sidebar settings.
- 2. Add inline controls with BlockControls for quick access.
- 3. Create a more dynamic and user-friendly block with custom settings.
In Day 24, we’ll explore block styles and CSS custom properties, allowing you to further enhance the visual appearance of your blocks.