WordPress Block Development Attributes and Controls

Summary: Learning about Attributes and Controls in WordPress Block Development.

Block Attributes

Block attributes define the data structure and state for a block. They are the dynamic properties of a block that are saved and retrieved from the database, representing the block’s data when stored in a post. Each block can have multiple attributes, and these attributes define how the block is rendered and what can be customized by the user.

Dynamic: Attributes store data that changes based on user interaction or input. This data can be simple (like text, booleans, or numbers) or more complex (like arrays or objects).
Declarative: Attributes are declared in the block’s block.json file or in the block’s registration function (typically registerBlockType).
Persisted in Post Content: When we save a post, the values of the attributes are saved with the post content, either in HTML comments or as metadata.
Accessed via Props: In our edit and save functions, block attributes are accessed through props provided by the block editor, which allows us to render dynamic content.

Declaring Block Attributes

Attributes are typically defined in the registerBlockType function or in the block.json file.

registerBlockType('my-namespace/my-block', {
    title: 'My Block',
    category: 'text',
    attributes: {
        content: {
            type: 'string',
            source: 'html',
            selector: 'p',
        },
        alignment: {
            type: 'string',
            default: 'none',
        },
    },
    // edit and save functions
});

content is a string attribute representing the HTML content of a paragraph tag.
alignment is another attribute of type string, with a default value of 'none'. It represents the text alignment of the content within the block.

String: For text, HTML, or any simple string value.
Boolean: For true/false values (e.g., toggles, visibility).
Number: For numeric values.
Array/Object: For lists of items or structured data (like image galleries or custom objects).

source: ‘html’: Retrieves data from the HTML structure (e.g., the inner content of a tag).
source: ‘meta’: Stores attributes in post meta fields rather than within the post content.
source: ‘attribute’: Retrieves attributes from HTML attributes (like class names, data attributes, etc.).
source: ‘query’: Used to retrieve multiple values from a repeated structure (like multiple list items).

registerBlockType('my-namespace/text-block', {
    title: 'Custom Text Block',
    icon: 'edit',
    category: 'text',
    attributes: {
        content: {
            type: 'string',
            source: 'html',
            selector: 'p',
        },
        textColor: {
            type: 'string',
            default: 'black',
        },
        fontSize: {
            type: 'number',
            default: 16,
        },
    },
    edit: ({ attributes, setAttributes }) => {
        const { content, textColor, fontSize } = attributes;

        return (
            <div>
                <RichText
                    tagName="p"
                    value={content}
                    onChange={(value) => setAttributes({ content: value })}
                    style={{ color: textColor, fontSize: fontSize }}
                />
            </div>
        );
    },
    save: ({ attributes }) => {
        const { content, textColor, fontSize } = attributes;

        return (
            <p style={{ color: textColor, fontSize: fontSize }}>
                {content}
            </p>
        );
    },
});

content is the rich text input the user types in.
textColor and fontSize store the style information.

Storing Attributes

Attributes can either be stored directly within the block’s comment tag in the post content, or they can be saved as metadata associated with the post. WordPress allows us to choose how we want to store these attributes using the source property.

Block Controls

Block controls represent the interactive controls that allow users to modify a block’s attributes through the WordPress block editor’s interface. These controls are typically added in the block toolbar or inspector sidebar (Block Inspector).

Block controls are responsible for modifying attributes and allow for real-time interaction with the block’s settings. Gutenberg provides several higher-order components (HoCs) to create common controls.

Text Inputs
Range Sliders
Dropdown Menus
Color Pickers
Toggle Switches

The block toolbar sits above the block and contains controls that are relevant to the block’s context. These controls are commonly used for text alignment, inline formatting, etc. They provide a compact, in-context way for users to modify block attributes.

import { BlockControls } from '@wordpress/block-editor';
import { AlignmentToolbar } from '@wordpress/components';

edit: ({ attributes, setAttributes }) => {
    return (
        <div>
            <BlockControls>
                <AlignmentToolbar
                    value={ attributes.alignment }
                    onChange={ ( newAlign ) => setAttributes( { alignment: newAlign } ) }
                />
            </BlockControls>

            <RichText
                tagName="p"
                value={ attributes.content }
                onChange={ ( content ) => setAttributes( { content } ) }
                style={ { textAlign: attributes.alignment } }
            />
        </div>
    );
}

The BlockControls component is used to add toolbar controls.
The AlignmentToolbar is a pre-built toolbar component from Gutenberg that allows users to change the text alignment of the content.

Inspector Controls

Inspector Controls are the settings that appear in the right-hand sidebar of the editor when a block is selected. These controls are often used for less frequently modified settings or for options that don’t require immediate visual feedback in the block.

import { InspectorControls } from '@wordpress/block-editor';
import { PanelBody, ColorPalette, RangeControl } from '@wordpress/components';

edit: ({ attributes, setAttributes }) => {
    const { textColor, fontSize } = attributes;

    return (
        <div>
            <InspectorControls>
                <PanelBody title="Text Settings">
                    <p>Text Color</p>
                    <ColorPalette
                        value={ textColor }
                        onChange={ ( newColor ) => setAttributes( { textColor: newColor } ) }
                    />
                    <RangeControl
                        label="Font Size"
                        value={ fontSize }
                        onChange={ ( newSize ) => setAttributes( { fontSize: newSize } ) }
                        min={ 12 }
                        max={ 40 }
                    />
                </PanelBody>
            </InspectorControls>

            <RichText
                tagName="p"
                value={ attributes.content }
                onChange={ ( content ) => setAttributes( { content } ) }
                style={{ color: textColor, fontSize: fontSize }}
            />
        </div>
    );
}

InspectorControls wraps the controls we want to place in the sidebar.
ColorPalette provides a UI for selecting a color.
RangeControl allows the user to select a font size using a slider.

Common Block Controls

AlignmentToolbar: For setting text alignment (left, right, center, justified).
ColorPalette: For color selection.
FontSizePicker: For selecting font size.
RangeControl: For selecting numeric values, such as font size, image size, etc.
TextControl: For plain text input fields.
ToggleControl: For boolean toggles (e.g., true/false, yes/no).

edit: ({ attributes, setAttributes }) => {
    return (
        <div>
            <BlockControls>
                <AlignmentToolbar
                    value={ attributes.alignment }
                    onChange={ ( newAlign ) => setAttributes( { alignment: newAlign } ) }
                />
            </BlockControls>

            <InspectorControls>
                <PanelBody title="Text Settings">
                    <ColorPalette
                        value={ attributes.textColor }
                        onChange={ ( newColor ) => setAttributes( { textColor: newColor } ) }
                    />
                    <RangeControl
                        label="Font Size"
                        value={ attributes.fontSize }
                        onChange={ ( newSize ) => setAttributes( { fontSize: newSize } ) }
                        min={ 12 }


 max={ 40 }
                    />
                </PanelBody>
            </InspectorControls>

            <RichText
                tagName="p"
                value={ attributes.content }
                onChange={ ( content ) => setAttributes( { content } ) }
                style={ { textAlign: attributes.alignment, color: attributes.textColor, fontSize: attributes.fontSize } }
            />
        </div>
    );
}