Creating Custom Sidebar Panels

Sidebar panels are collapsible sections in the right sidebar of the block editor. By default, WordPress includes panels like “Post” (which manages post-wide settings) and “Block” (specific to the selected block). Custom sidebar panels extend these options by allowing you to create additional sections with your fields, inputs, and controls.

Why Use Custom Sidebar Panels?

Custom sidebar panels are a great way to add more functionality to the WordPress editor without cluttering the main interface. Whether you want to add advanced settings for specific blocks or allow users to configure post metadata like SEO fields, sidebar panels are the perfect place to house these controls.

Example Use Cases:

• Post Settings: A custom panel for adding SEO metadata, controlling social media sharing, or toggling visibility options.
• Block-Specific Controls: Let’s say you want to give users control over the layout or appearance of a hero block. A sidebar panel can contain options like custom padding, background color, or typography choices.
• Plugin Settings: Sidebar panels can also provide users with plugin-specific options, such as configuring a promotional banner or newsletter sign-up form.

What Can You Do with Sidebar Panels?

Custom sidebar panels are flexible and versatile, allowing you to:

1. Extend Existing Features: Add additional settings to existing blocks or posts without overwhelming the main editor.
2. Create New Panels: Build panels that manage settings for custom post types, taxonomies, or plugin features.
3. Contextualize Settings: You can even show or hide specific settings based on what the user is editing, making the experience more intuitive.

By placing these additional controls in the sidebar, the main editor remains focused on content creation, while advanced options are easily accessible for users who need them.

Benefits of Custom Sidebar Panels

Why should you consider adding custom sidebar panels to your projects? There are several reasons:

• Cleaner User Interface: Instead of loading up the main content area with tons of settings, you can neatly organize them into a sidebar panel.
• Better User Experience: By keeping complex options in a sidebar, users can focus on what matters most—creating content—without feeling overwhelmed.
• Modular Design: Sidebar panels allow you to break down complex settings into manageable sections, making the experience more structured and organized.

Example
Take a custom block for a testimonial section. You might want users to control how many columns to display, the background color, and the text alignment. Instead of adding these options directly in the block controls, you can place them in a sidebar panel, giving users an organized way to fine-tune their block settings.

How to create custom Sidebar Panels

With the recent updates in the Gutenberg Block Editor, creating custom sidebar panels is more streamlined, and you can now easily extend both block-specific settings and document-wide settings. There are two main components for adding sidebar panels i.e, PluginSidebar and PluginDocumentSettingPanel

PluginSidebar vs PluginDocumentSettingPanel

• PluginSidebar: Adds a completely new panel to the block editor. This is useful when you want to provide block-specific settings or additional controls that are not related to the post or document as a whole.
• PluginDocumentSettingPanel: Integrates into the Document Settings section, which already includes options like Permalink, Categories, and Featured Image. This is ideal when your settings apply to the entire post or page.

When to Use Each

• Use PluginSidebar when the options are specific to a block or you want to group additional controls in their section.
• Use PluginDocumentSettingPanel when your settings are related to the document (post, page, or custom post type), such as metadata, SEO settings, or any global settings that affect the entire content piece.

Example: Using PluginDocumentSettingPanel

Here’s how you can add a custom panel to the Document Settings area using PluginDocumentSettingPanel.

import { registerPlugin } from "@wordpress/plugins";
import { PluginDocumentSettingPanel } from "@wordpress/edit-post";
import { PanelBody, TextControl } from "@wordpress/components";
import { __ } from "@wordpress/i18n";

const MyDocumentPanel = () => (
    <PluginDocumentSettingPanel
        name="my-document-panel"
        title={__("Custom Document Panel")}
        className="my-document-panel-class"
    >
        <PanelBody title={__("Custom Settings")}>
            <TextControl
                label={__("Custom Field")}
                value={someDocumentValue}
                onChange={(newValue) => setSomeDocumentValue(newValue)}
            />
        </PanelBody>
    </PluginDocumentSettingPanel>
);

registerPlugin("my-document-panel", { render: MyDocumentPanel });

In this example:

• PluginDocumentSettingPanel is used to add a custom section to the “Document Settings” sidebar.
• The TextControl input allows the user to enter document-specific values, such as custom metadata or other global settings.

Example: Promotional Strip Options Using PluginDocumentSettingPanel

In this example, we are creating a Promotional Strip Options panel within the Document Settings using the PluginDocumentSettingPanel component. This is useful when you want the promotional strip settings to apply globally to the entire post or page, rather than to a specific block.

The panel we’re building contains:

1. A checkbox to toggle the visibility of the promotional strip.
2. A textarea to allow users to input content for the promotional strip, with a character limit of 280.

The implementation looks like this:

The implementation for this looks something like this:

const { registerPlugin } = wp.plugins;
const { PluginDocumentSettingPanel } = wp.editPost;
const { __ } = wp.i18n;
const { CheckboxControl, TextareaControl } = wp.components;
const { useSelect, useDispatch } = wp.data;

const RenderPromoOptionsMeta = () => {
    const ShouldShowPromo = useSelect(
        ( select ) =>
            select( 'core/editor' ).getEditedPostAttribute( 'meta' ).show_promotional_strip,
    );

    const PromoContent = useSelect(
        ( select ) =>
            select( 'core/editor' ).getEditedPostAttribute( 'meta' ).promotional_strip_content,
    );

    const { editPost } = useDispatch( 'core/editor' );

    const updatePromoContent = ( value ) => {
        if ( value.replace( /(<([^>]+)>)/gi, '' ).length > 280 ) {
            return;
        }
        editPost( { meta: { promotional_strip_content: value } } );
    };

    return (
        
            <CheckboxControl
                label={ __( 'Show Promotional Strip', 'custom-features' ) }
                help={ __(
                    'If checked, the promotional strip will be displayed on the front end.',
                    'custom-features',
                ) }
                checked={ ShouldShowPromo }
                onChange={ ( value ) =>
                    editPost( { meta: { show_promotional_strip: value } } )
                }
            />
            { ShouldShowPromo && (
                <TextareaControl
                    value={ PromoContent }
                    onChange={ updatePromoContent }
                    label={ __( 'Promotional Strip Content', 'custom-features' ) }
                    help={ __(
                        'Enter the content to be displayed in the promotional strip (max 280 characters).',
                        'custom-features',
                    ) }
                />
            ) }
        </>
    );
};

const PluginPromoOptionsMeta = () => {
    const postType = useSelect( ( select ) =>
        select( 'core/editor' ).getCurrentPostType(),
    );

    const allowedPostTypes = [ 'post', 'page', 'case-study', 'tutorials' ];

    return (
        
            { allowedPostTypes.includes( postType ) && (
                <PluginDocumentSettingPanel
                    name="promo_options"
                    title={ __( 'Promotional Strip Options', 'custom-features' ) }
                    className="page-options"
                >
                    <RenderPromoOptionsMeta />
                </PluginDocumentSettingPanel>
            ) }
        </>
    );
};

registerPlugin( 'plugin-promo-options', {
    render: PluginPromoOptionsMeta,
    icon: null,
} );

When to Choose PluginDocumentSettingPanel?

You should opt for PluginDocumentSettingPanel when your custom controls are related to:

• SEO Metadata: Adding fields for SEO descriptions or keywords that apply to the whole post.
• Global Layout Options: Settings like page templates, featured banners, or visibility toggles.
• Author Information: If you’re building something like an author metadata input panel.

This component is specifically designed for settings that influence the post or page as a whole, making it perfect for global document-level controls.

Custom Sidebar Panel Features

In this section, we’ll explore some advanced features such as interacting with the WordPress Data API, adding conditional logic, handling forms and validations, and even integrating with external APIs.

Interacting with the WordPress Data API

The WordPress Data API provides access to the block editor’s data store, allowing you to fetch and manipulate content, settings, and metadata in real time. This makes your sidebar panels far more dynamic and context-aware.

Example: Fetching and Updating Post Meta with the Data API

Let’s say you want to create a custom panel that retrieves and updates a post’s custom meta fields. You can interact with the post’s data store using the @wordpress/data package.

import { useSelect, useDispatch } from "@wordpress/data";
import { PanelBody, TextControl } from "@wordpress/components";
import { __ } from "@wordpress/i18n";

const CustomMetaPanel = () => {
    const meta = useSelect(
        (select) => select("core/editor").getEditedPostAttribute("meta"),
        []
    );
    const { editPost } = useDispatch("core/editor");
    const updateMeta = (newMetaValue) => {
        editPost({ meta: { ...meta, custom_meta_key: newMetaValue } });
    };

    return (
        <PanelBody title={__("Custom Meta Settings")}>
            <TextControl
                label={__("Custom Meta Field")}
                value={meta.custom_meta_key}
                onChange={updateMeta}
            />
        </PanelBody>
    );
};

export default CustomMetaPanel;

In this example:

• useSelect retrieves the current post’s metadata.
• useDispatch allows you to update the post’s metadata dynamically as users input new values.

This makes your sidebar panel an interactive interface for users to manipulate post-level data in real time.

Adding Conditional Logic to Sidebar Panels

There are cases when you may want to show or hide specific parts of a sidebar panel based on the current block, user role, or even content type.

Example: Conditional Panel Display Based on Block Type

Let’s say you want a particular sidebar panel to show only when the currently selected block is an image block. Here’s how you can achieve that:

import { useSelect } from "@wordpress/data";
import { PluginSidebar } from "@wordpress/edit-post";
import { PanelBody, TextControl } from "@wordpress/components";
import { __ } from "@wordpress/i18n";

const ImageBlockSettings = () => {
    const isImageBlock = useSelect((select) => {
        const selectedBlock = select("core/block-editor").getSelectedBlock();
        return selectedBlock && selectedBlock.name === "core/image";
    }, []);

    if (!isImageBlock) return null;

    return (
        <PluginSidebar
            name="image-block-settings"
            title={__("Image Block Settings")}
            icon="format-image"
        >
            <PanelBody title={__("Custom Image Settings")}>
                <TextControl label={__("Alt Text")} />
            </PanelBody>
        </PluginSidebar>
    );
};

export default ImageBlockSettings;

This code ensures that the sidebar panel only appears when the selected block is an image block, keeping the user interface clean and relevant.

Handling Forms and Validations in Sidebar Panels

Forms and validations are critical when you need to ensure users input correct or complete information. Whether it’s validating a URL, restricting input length, or requiring certain fields, handling validation inside a custom sidebar panel is a must.

Example: Simple Form with Validations

import { useState } from "react";
import { PanelBody, TextControl, Button } from "@wordpress/components";

const FormWithValidation = () => {
    const [inputValue, setInputValue] = useState("");
    const [error, setError] = useState("");
    const validateInput = () => {
        if (!inputValue) {
            setError("This field is required.");
        } else if (inputValue.length < 5) {
            setError("Input must be at least 5 characters.");
        } else {
            setError("");
            // Your further logic will go here.
        }
    };

    return (
        <PanelBody title={__("Form with Validation")}>
            <TextControl
                label={__("Input Field")}
                value={inputValue}
                onChange={(value) => setInputValue(value)}
                help={error}
                isError={!!error}
            />
            <Button isPrimary onClick={validateInput}>
                {__("Submit")}
            </Button>
        </PanelBody>
    );
};

export default FormWithValidation;

In this example:

• Input Validation checks whether the field is empty and enforces a minimum length.
• The error message is dynamically displayed using the help prop on the TextControl.

This setup ensures that users can’t proceed without meeting the validation requirements, improving data integrity.

Integrating with External APIs

Advanced sidebar panels can interact with external services through the WordPress REST API or any other API. This is particularly useful when you need to fetch data from an external source or submit user inputs to a third-party service.

Example: Fetching Data from an External API

import { useEffect, useState } from "react";
import { PanelBody, Button } from "@wordpress/components";

const FetchApiDataPanel = () => {
    const [apiData, setApiData] = useState(null);
    useEffect(() => {
        fetch("https://api.example.com/data")
            .then((response) => response.json())
            .then((data) => setApiData(data))
            .catch((error) => console.error("Error fetching data:", error));
    }, []);

    return (
        <PanelBody title={__("API Data")}>
            {apiData ? (
                <p>{JSON.stringify(apiData)}</p>
            ) : (
                <Button isBusy>{__("Loading data...")}</Button>
            )}
        </PanelBody>
    );
};

export default FetchApiDataPanel;

In this example:

• The fetch function is used to pull data from an external API, and the panel dynamically displays the fetched data.
• This makes it easy to integrate external services directly within your custom sidebar panels, enhancing the capabilities of your WordPress editor.

Styling Custom Sidebar Panels

A good sidebar panel is not just functional, it’s also well-designed. WordPress provides an excellent component library to ensure your sidebar panels have a consistent look and feel. However, there may be cases where you need to apply custom styles or even handle dark mode.

Using the WordPress Component Library

WordPress offers a wide range of pre-built components like buttons, text inputs, color pickers, and more. These components are styled to fit seamlessly into the Gutenberg UI, ensuring your sidebar panel matches the overall editor experience.

Example: Creating a Consistent UI with Components

import { PanelBody, TextControl, ColorPicker, Button } from '@wordpress/components';

const StyledPanel = () => (

    <PanelBody title={ __( 'Styled Panel' ) }>
        <TextControl label={ __( 'Enter Text' ) } />
        <ColorPicker />
        <Button isPrimary>{ __( 'Submit' ) }</Button>
    </PanelBody>
);

Here, you’re using WordPress UI components like TextControl, ColorPicker, and Button to maintain a consistent style in your panel.

Custom CSS for Sidebar Panels

While the default component library handles most cases, you can also apply custom CSS for specific design needs.

Example: Applying Custom Styles

.my-custom-panel .components-panel__body {
    background-color: #f0f0f0;
    padding: 20px;
}

By targeting your custom sidebar panel with specific CSS classes, you can override styles like background colors, padding, or even borders. This flexibility allows you to match your panel’s design with your theme or plugin’s branding.