Creating Custom Block Toolbar

Block toolbars are an essential part of the WordPress editor experience, offering users quick access to frequently used controls directly on the block itself. These toolbars provide inline, contextual actions like text formatting, alignment, or custom features that are relevant to the selected block. In this guide, we’ll walk through how to create custom block toolbars for your blocks and enhance the editing experience.

Understanding the Block Toolbar

In the Gutenberg editor, the BlockControls component is used to add custom buttons and actions to the block toolbar. This toolbar typically appears above the block when the user selects it, providing easy access to important settings.

The toolbar can include buttons for:

• Text formatting: Bold, italic, underline, etc.
• Alignment: Align left, center, or right.
• Custom actions: Any custom functionality that suits your block’s behavior.

Why do Toolbars Matter?
Toolbars enhance usability by allowing users to perform quick actions without diving into sidebar settings, making the block editor more intuitive and efficient.

Using the BlockControls Component

The BlockControls component is the foundation for adding toolbar buttons to your blocks. By wrapping your custom toolbar buttons inside, they will integrate seamlessly into the WordPress editor, appearing when the user selects the associated block.

Example: Adding a Custom Toolbar Button

Let’s start by adding a simple button to the toolbar for a custom action. In this case, we’ll add a “Bold Text” button that toggles bold formatting on the selected text.

import { __ } from "@wordpress/i18n";
import { BlockControls } from "@wordpress/block-editor";
import { ToolbarGroup, ToolbarButton } from "@wordpress/components";

const Edit = (props) => {
    const { attributes, setAttributes } = props;
    const { isBold } = attributes;
    const toggleBold = () => setAttributes({ isBold: !isBold });

    return (
        <div>
            <BlockControls>
                <ToolbarGroup>
                    <ToolbarButton
                        label={__("Bold Text")}
                        icon="editor-bold"
                        isActive={isBold}
                        onClick={toggleBold}
                    />
                </ToolbarGroup>
            </BlockControls>

            <p style={{ fontWeight: isBold ? "bold" : "normal" }}>
                This is some text content.
            </p>
        </div>
    );
};

export default Edit;

• BlockControls: Wraps the toolbar buttons and ensures they appear when the block is selected.
• ToolbarButton: Adds a button with an icon for “Bold Text” formatting. The button toggles between bold and normal text states based on the “isBold” attribute.

Grouping Toolbar Buttons

To keep toolbars organized, you can group related actions using the ToolbarGroup component. This ensures that users can find relevant actions in one place without cluttering the interface.

Example: Grouping Alignment Buttons in the Toolbar

import { BlockControls } from "@wordpress/block-editor";
import { ToolbarGroup, ToolbarButton } from "@wordpress/components";

const Edit = (props) => {
    const { attributes, setAttributes } = props;
    const { textAlign } = attributes;
    const setAlignment = (alignment) => setAttributes({ textAlign: alignment });

    return (
        <div>
            <BlockControls>
                <ToolbarGroup>
                    <ToolbarButton
                        label="Align Left"
                        icon="editor-alignleft"
                        onClick={() => setAlignment("left")}
                        isActive={textAlign === "left"}
                    />

                    <ToolbarButton
                        label="Align Center"
                        icon="editor-aligncenter"
                        onClick={() => setAlignment("center")}
                        isActive={textAlign === "center"}
                    />

                    <ToolbarButton
                        label="Align Right"
                        icon="editor-alignright"
                        onClick={() => setAlignment("right")}
                        isActive={textAlign === "right"}
                    />
                </ToolbarGroup>
            </BlockControls>
            <p style={{ textAlign }}>{"Aligned text"}</p>
        </div>
    );
};

export default Edit;

• ToolbarGroup: Groups multiple related toolbar buttons together.
• ToolbarButton: Adds alignment options (left, center, right) and visually highlights the active button using the isActive prop.

Using ToolbarDropdownMenu for Multiple Actions

Sometimes, you may have a set of related actions that should be grouped into a dropdown menu rather than individual buttons. This is especially useful when you have more than a few options.

Example: Adding a Dropdown Menu for Text Styles

import { ToolbarGroup, ToolbarDropdownMenu } from "@wordpress/components";

const Edit = (props) => {
    const { attributes, setAttributes } = props;
    const { textStyle } = attributes;
    const setTextStyle = (style) => setAttributes({ textStyle: style });

    return (
        <div>
            <BlockControls>
                <ToolbarGroup>
                    <ToolbarDropdownMenu
                        icon="editor-textcolor"
                        label="Text Style"
                        controls={[
                            { title: "Normal", onClick: () => setTextStyle("normal") },

                            { title: "Italic", onClick: () => setTextStyle("italic") },

                            { title: "Bold", onClick: () => setTextStyle("bold") },
                        ]}
                    />
                </ToolbarGroup>
            </BlockControls>

            <p
                style={{
                    fontStyle: textStyle === "italic" ? "italic" : "normal",
                    fontWeight: textStyle === "bold" ? "bold" : "normal",
                }}
            >
                This is styled text.
            </p>
        </div>
    );
};

export default Edit;

ToolbarDropdownMenu: Creates a dropdown menu with multiple text style options. Users can switch between normal, italic, or bold text styles by selecting from the dropdown.

Best Practices for Designing Block Toolbars

1. Keep the Toolbar Focused

• Toolbars should provide only the most frequently used or relevant controls for the block. Avoid overloading the toolbar with too many options; less critical settings should be placed in the block’s sidebar settings.

2. Group Related Actions

• Group actions that belong together, like alignment or text formatting, to avoid clutter and make it easy for users to find related controls.

3. Use Familiar Icons

• Stick to WordPress’s built-in icons (via the Dashicons library) for consistency and familiarity. Users should be able to recognize the actions at a glance.

4. Provide Clear Labels

• Each button should have a clear and accessible label that describes the action. Use tooltips when necessary to ensure accessibility for all users.

5. Handle Loading and Disabled States

• If the action triggered by a toolbar button involves asynchronous operations (like saving data or fetching content), make sure to handle loading and disabled states appropriately.

Example: Handling a Save Operation with a Disabled Button

const Edit = (props) => {
    const { attributes, setAttributes } = props;

    const { isSaving } = attributes;

    const handleSave = () => {
        // Simulate a save operation
        setAttributes({ isSaving: true });
        setTimeout(() => setAttributes({ isSaving: false }), 2000);
    };

    return (
        <div>
            <BlockControls>
                <ToolbarGroup>
                    <ToolbarButton
                        label="Save"
                        icon="save"
                        onClick={handleSave}
                        isBusy={isSaving}
                        disabled={isSaving}
                    />
                </ToolbarGroup>
            </BlockControls>
            <p>{isSaving ? "Saving..." : "Content"}</p>
        </div>
    );
};

ToolbarButton with isBusy: The button shows a “loading” state when a save operation is in progress, preventing the user from clicking multiple times.

Making Toolbars Accessible

Toolbars need to be fully accessible for all users, including those using screen readers or keyboard navigation.

Accessibility Tips:

• Use meaningful ARIA labels for buttons.
• Ensure that users can navigate and activate toolbar buttons using the keyboard (focus states and tab order should be clear).
• Provide tooltips for users who rely on visual cues.

Example: Accessible Button with ARIA Label

<ToolbarButton
    label="Bold Text"
    icon="editor-bold"
    onClick={ toggleBold }
    aria-label="Toggle bold text"
/>

ARIA Label: Provides an accessible description for screen readers to convey the purpose of the button.

Keyboard Accessibility and Shortcuts in Toolbars

For a great user experience, especially for power users, keyboard shortcuts should be provided where possible. Users should be able to navigate and activate toolbar buttons without relying solely on the mouse.

Best Practices:

• Implement keyboard navigation to move between toolbar buttons (using the tab key).
• Add keyboard shortcuts for frequently used actions (e.g., Ctrl+B for bold text).

Example: Adding Keyboard Shortcuts to Toolbar Buttons

import { ToolbarButton } from "@wordpress/components";
import { useEffect } from "react";

const Edit = (props) => {
    const { attributes, setAttributes } = props;
    const { isBold } = attributes;
    const toggleBold = () => setAttributes({ isBold: !isBold });
    // Adding a keyboard shortcut for bold (Ctrl + B)

    useEffect(() => {
        const handleKeyDown = (event) => {
            if (event.ctrlKey && event.key === "b") {
                event.preventDefault();

                toggleBold();
            }
        };

        window.addEventListener("keydown", handleKeyDown);

        return () => {
            window.removeEventListener("keydown", handleKeyDown);
        };
    }, [isBold]);

    return (
        <div>
            <BlockControls>
                <ToolbarButton
                    label="Bold Text"
                    icon="editor-bold"
                    onClick={toggleBold}
                    isActive={isBold}
                    aria-label="Toggle bold text"
                />
            </BlockControls>

            <p style={{ fontWeight: isBold ? "bold" : "normal" }}>
                This is some boldable text.
            </p>
        </div>
    );
};

export default Edit;

• Keyboard Shortcut: The useEffect hook listens for the Ctrl+B key combination and triggers the bold action. This is useful for power users who rely on keyboard shortcuts for efficiency.
• ToolbarButton: The bold button remains in the toolbar for users who prefer to click, but keyboard users can trigger the same action without leaving the keyboard.

Contextual Toolbars for Dynamic Block States

In some cases, your block might need to display different toolbar buttons depending on the current state of the block. For example, a block could offer different actions based on the selected view mode (list view vs grid view).

Example: Contextual Toolbar for Grid and List Views

{ isGridView ? (
    <ToolbarButton label="Switch to List" icon="list-view" onClick={ switchToList } />
) : (
    <ToolbarButton label="Switch to Grid" icon="grid-view" onClick={ switchToGrid } />
) }

In this example, the toolbar dynamically changes depending on whether the user is in a grid view or a list view. This ensures the toolbar remains relevant and only shows actions that make sense for the current context.

Explanation:

• The toolbar switches between two buttons, one to switch to list view and one to switch to grid view, depending on the current block state (isGridView).
• This approach improves the user experience by keeping the interface uncluttered and focused on the current task.

Handling Loading and Disabled States in Toolbar Actions

When toolbar actions involve asynchronous processes, such as saving data or fetching content, it’s crucial to handle loading states properly. This provides feedback to users, prevents accidental multiple clicks, and improves the overall user experience.

Best Practices:

• Show a loading indicator when an action is in progress.
• Disable the toolbar button while the action is being processed to prevent multiple clicks.

Example: Toolbar Button with Loading and Disabled States

const Edit = (props) => {
    const { attributes, setAttributes } = props;
    const { isSaving } = attributes;

    const handleSave = () => {
        setAttributes({ isSaving: true });
        setTimeout(() => setAttributes({ isSaving: false }), 2000); // Simulating save delay
    };

    return (
        <div>
            <BlockControls>
                <ToolbarButton
                    label="Save"
                    icon="save"
                    onClick={handleSave}
                    isBusy={isSaving}
                    disabled={isSaving}
                />
            </BlockControls>
            <p>{isSaving ? "Saving content..." : "Content saved!"}</p>
        </div>
    );
};

• isBusy: The ToolbarButton shows a spinner icon to indicate that the save operation is in progress.
• disabled: The button is disabled while the content is being saved, preventing multiple save actions at once.

Performance Considerations for Custom Toolbars

Custom toolbars, especially those involving complex operations or multiple components, can affect the editor’s performance if not optimized properly. Follow these performance tips to ensure smooth operation:

Minimize Re-Renders

useMemo and useCallback to avoid unnecessary re-renders, especially when handling the toolbar button state.

Lazy Load Data

If your toolbar relies on external data (such as pulling items from an API), only load the data when needed.

Reduce Expensive Operations

Avoid running heavy computations or data fetches on every render of the block.

Example: Optimizing Toolbar Actions with useMemo and useCallback

import { useCallback, useMemo } from "react";
import { ToolbarButton } from "@wordpress/components";

const Edit = (props) => {
    const { attributes, setAttributes } = props;
    const { isBold } = attributes;

    const toggleBold = useCallback(() => {
        setAttributes({ isBold: !isBold });
    }, [isBold]);

    const toolbarLabel = useMemo(() => {
        return isBold ? "Unbold Text" : "Bold Text";
    }, [isBold]);

    return (
        <div>
            <BlockControls>
                <ToolbarButton
                    label={toolbarLabel}
                    icon="editor-bold"
                    onClick={toggleBold}
                    isActive={isBold}
                />
            </BlockControls>

            <p style={{ fontWeight: isBold ? "bold" : "normal" }}>
                This is boldable text.
            </p>
        </div>
    );
};

• useCallback: Memoizes the toggleBold function so that it doesn’t get recreated on every render, improving performance.
• useMemo: Caches the toolbar label (Bold Text or Unbold Text) so it only recalculates when the isBold state changes.

Creating custom block toolbars in the WordPress editor enhances the user experience by providing quick, intuitive access to block controls. By leveraging BlockControls, ToolbarButton, and ToolbarDropdownMenu, you can build toolbars that are efficient, accessible, and tailored to your block’s functionality.