WordPress Block Supports API: Enable Color, Typography, and Spacing in Custom Blocks

WordPress’s Block Supports API is a declarative system for adding common UI controls to custom blocks without manually implementing each control in JavaScript. By adding a supports key to the block metadata in block.json (or as the third argument to registerBlockType()), a block can opt into standardized controls for typography, color, spacing, border, and more — and WordPress automatically adds the corresponding sidebar panels, generates the CSS, and saves the settings as block attributes. Without the Supports API, a block developer has to manually register attributes for font size, text color, and background color, implement InspectorControls panels for each, apply styles to the editor preview, and generate and output inline styles on the front end. The Supports API handles all of that automatically. By 2020, colour and background-color supports were stable in WordPress 5.3+, and typography support was being progressively introduced — making this the right time to adopt the API in new blocks.

Problem: Your custom Gutenberg block needs colour controls (text and background), font-size selection from the theme's type scale, and alignment support — without writing a custom InspectorControls panel for each. You also need the front-end output to apply these styles correctly.

Solution: Add a supports object to block.json enabling color, typography, and align. Use the useBlockProps() hook in JavaScript so the generated class names and inline styles are applied to the block wrapper automatically.

// block.json
{
    "apiVersion": 2,
    "name": "my-plugin/callout",
    "title": "Callout",
    "category": "text",
    "supports": {
        "align": [ "wide", "full" ],
        "color": {
            "text": true,
            "background": true,
            "gradients": true
        },
        "typography": {
            "fontSize": true,
            "lineHeight": true
        },
        "spacing": {
            "padding": true,
            "margin":  [ "top", "bottom" ]
        }
    },
    "attributes": {
        "content": { "type": "string", "source": "html", "selector": "p" }
    }
}

// edit.js — useBlockProps() applies all supports-generated classes + styles
import { useBlockProps, RichText } from '@wordpress/block-editor';

export default function Edit( { attributes, setAttributes } ) {
    // blockProps includes: className (with has-text-color etc.), style (inline styles)
    const blockProps = useBlockProps( {
        className: 'my-callout',
    } );

    return (
        <div { ...blockProps }>
            <RichText
                tagName="p"
                value={ attributes.content }
                onChange={ ( content ) => setAttributes( { content } ) }
                placeholder="Callout text…"
            />
        </div>
    );
}

// save.js — useBlockProps.save() for the saved static markup
import { useBlockProps, RichText } from '@wordpress/block-editor';

export default function Save( { attributes } ) {
    const blockProps = useBlockProps.save( {
        className: 'my-callout',
    } );

    return (
        <div { ...blockProps }>
            <RichText.Content tagName="p" value={ attributes.content } />
        </div>
    );
}

<?php
// PHP: register the block from block.json — supports are read automatically
register_block_type( __DIR__ . '/build/callout' );

// For a server-side rendered block that uses supports:
register_block_type( __DIR__ . '/build/callout', [
    'render_callback' => function ( array $attributes, string $content ) {
        // get_block_wrapper_attributes() generates the class and style attributes
        // from supports settings — use it in the render callback
        $wrapper = get_block_wrapper_attributes( [ 'class' => 'my-callout' ] );
        return sprintf( '<div %s><p>%s</p></div>', $wrapper,
            wp_kses_post( $attributes['content'] ?? '' ) );
    },
] );

NOTE: Block Supports generate CSS class names like has-text-color, has-vivid-red-color, has-large-font-size which are defined by the active theme's theme.json. If your theme doesn't define these values, the colours and sizes won't render visually even though the class names are applied. For custom colours selected outside the theme palette, WordPress uses inline styles (e.g. style="color:#ff5733") instead of class names. Always use useBlockProps() in the edit function and useBlockProps.save() in the save function — manually applying styles and classes without these hooks breaks the block validation system when the attributes change.