WordPress.org

WordPress Developer Blog

Using block inspector sidebar groups

Building custom blocks generally means adding controls to the Block Inspector sidebar. You do that with the <InspectorControls> component, and until WordPress 6.2 arrived, the settings were all in one place.

Before WordPress 6.2

WordPress 6.2 brought tabs to the Block Inspector. Now, items that control settings and ones that manage styles live under separate tabs, so you can see more clearly which you’re working on..

As you can see, now you have a lot more places to put  your custom controls. How do you target them?

Available Locations

The process has not changed; you still use the <InspectorControls>  component. But in 6.2, the new group prop lets you target where the control will appear.

group accepts these predefined locations, which each target a specific area::

  • settings (default)
  • styles
  • color
  • typography
  • dimensions
  • border
  • advanced

Settings and Styles Panels

The settings and styles options target the Settings and Styles panels and will add items to the bottom of each. If the group prop is missing from <InspectorControls> (or its value is set to settings), the control will go into the Settings section.

For example, this code adds a custom control to the Settings tab.

/**
 * WordPress dependencies
 */
import { __ } from '@wordpress/i18n';
import { useBlockProps, InspectorControls } from '@wordpress/block-editor';
import { PanelBody } from '@wordpress/components';

/**
 * Internal dependencies
 */
import './editor.scss';

/**
 * Edit Component
 */
export default function Edit() {
	return (
		<div { ...useBlockProps() }>
			{ __(
				'Inspector Control Groups Block',
				'inspector-control-groups'
			) }
			<InspectorControls>
				<PanelBody
					title={ __(
						'Custom Block Controls',
						'inspector-control-groups'
					) }
				>
					{ __(
						'Custom block controls added using the InspectorControls component',
						'inspector-control-groups'
					) }
				</PanelBody>
			</InspectorControls>
		</div>
	);
}

If you wanted to have this control appear in the Styles tab instead, you could add the group prop and set it to styles.

export default function Edit() {
	return (
		<div { ...useBlockProps() }>
			{ __(
				'Inspector Control Groups Block',
				'inspector-control-groups'
			) }
			<InspectorControls group="styles">
				<PanelBody
					title={ __(
						'Custom Block Controls',
						'inspector-control-groups'
					) }
				>
					{ __(
						'Custom block controls added using the InspectorControls component',
						'inspector-control-groups'
					) }
				</PanelBody>
			</InspectorControls>
		</div>
	);
}

You might notice that the Settings tab has disappeared. That’s because your controls are no longer targeting the settings section, and there are no other controls that will show up there. If you added another <InspectorControls> component without a group prop (or set it to settings), the Settings tab would appear.

Inside the Styles Panel

It’s pretty easy to target each of the inner panels of the Styles tab. You do it by passing  one of color, typography, dimensions, or border to the group prop.

export default function Edit() {
	return (
		<div { ...useBlockProps() }>
			{ __(
				'Inspector Control Groups Block',
				'inspector-control-groups'
			) }
			<InspectorControls group="color">
				<div className="full-width-control-wrapper">
					{ __(
						"I'm in the colors group!",
						'inspector-control-groups'
					) }
				</div>
			</InspectorControls>
			<InspectorControls group="typography">
				<div className="full-width-control-wrapper">
					{ __(
						"I'm in the typography group!",
						'inspector-control-groups'
					) }
				</div>
			</InspectorControls>
			<InspectorControls group="dimensions">
				<div className="full-width-control-wrapper">
					{ __(
						"I'm in the dimensions group!",
						'inspector-control-groups'
					) }
				</div>
			</InspectorControls>
			<InspectorControls group="border">
				<div className="full-width-control-wrapper">
					{ __(
						"I'm in the border group!",
						'inspector-control-groups'
					) }
				</div>
			</InspectorControls>
		</div>
	);
}

One thing to note here: the items in these areas are using CSS Grid. To have your component span the full width you will need to add some CSS to the wrapper element in your blocks stylesheet.

.full-width-control-wrapper {
	grid-column: 1 / -1;
}

The Advanced area

You insert items into the Advanced area by setting group to advanced or by using the <InspectorAdvancedControls> component.

export default function Edit() {
	return (
		<div { ...useBlockProps() }>
			{ __(
				'Inspector Control Groups Block',
				'inspector-control-groups'
			) }
			<InspectorAdvancedControls>
				{ __(
					"I'm in the advanced group!",
					'inspector-control-groups'
				) }
			</InspectorAdvancedControls>

			<InspectorControls group="advanced">
				{ __(
					"I'm in the advanced group!",
					'inspector-control-groups'
				) }
			</InspectorControls>
		</div>
	);
}

This article has barely touched the surface–it’s brief by design. But with this new feature, you’ll have a lot more control over block UI. And as you explore, you’ll no doubt find many more ways to build simple and intuitive UIs.

Thank you to @bph, @greenshady, @ndiego, @marybaum, and @mburridge for reviewing this post.

3 responses to “Using block inspector sidebar groups”

  1. Ryan Welcher Avatar

    As of the time of writing, there is no documentation around the group prop. You can follow the status via this issue – https://github.com/WordPress/gutenberg/issues/51198

    1. Lars Faye Avatar

      The time it took to make this blog post, they could have just written some documentation.

      1. Birgit Pauli-Haack Avatar

        Hi Lars,
        We do have a fairly large backlog of update to the documentation, indeed. And it will be updated in due time. In the meantime, it was important that developers get the update about the “groups” as it improves the flexibility and granularity how block editor can be extended. Is there something eles you’re trying to find that you’re not seeing?

Leave a Reply

Your email address will not be published. Required fields are marked *