Block Supports API - Gutenberg Block Editor

The Block Supports API allows blocks to declare support for certain editor features. When you enable a support feature, the editor automatically:

Registers additional attributes on the block
Provides UI controls in the editor
Applies the settings through useBlockProps

This eliminates the need to manually build controls for common features.

How Block Supports Work

Declare supports in your block.json:

{
    "supports": {
        "color": {
            "background": true,
            "text": true,
            "gradients": true
        },
        "spacing": {
            "margin": true,
            "padding": true
        },
        "typography": {
            "fontSize": true,
            "lineHeight": true
        }
    }
}

Then use useBlockProps to apply the generated properties:

import { useBlockProps } from '@wordpress/block-editor';

function BlockEdit() {
    const blockProps = useBlockProps();
    // All support features are automatically applied
    return <div { ...blockProps }>Hello World!</div>;
}

Color Support

color

object

Enables color-related controls and attributes

Background Color

{
    "supports": {
        "color": {
            "background": true
        }
    }
}

This automatically adds:

backgroundColor attribute (string) - Stores preset slug
style.color.background attribute - Stores custom color value
Color picker UI in the editor

Text Color

{
    "supports": {
        "color": {
            "text": true
        }
    }
}

Adds:

textColor attribute - Preset slug
style.color.text attribute - Custom value

Gradients

{
    "supports": {
        "color": {
            "gradients": true,
            "background": false  // Usually disabled with gradients
        }
    }
}

Adds:

gradient attribute - Preset gradient slug
style.color.gradient attribute - Custom gradient

Link, Heading, and Button Colors

Available since WordPress 6.5

{
    "supports": {
        "color": {
            "link": true,
            "heading": true,
            "button": true
        }
    }
}

Real Example: Paragraph Block

From packages/block-library/src/paragraph/block.json:

{
    "supports": {
        "color": {
            "gradients": true,
            "link": true,
            "__experimentalDefaultControls": {
                "background": true,
                "text": true
            }
        }
    }
}

Spacing Support

spacing

object

Enables margin, padding, and blockGap controls

Margin and Padding

{
    "supports": {
        "spacing": {
            "margin": true,
            "padding": true
        }
    }
}

Specific Sides

Control which sides can be adjusted:

{
    "supports": {
        "spacing": {
            "margin": [ "top", "bottom" ],
            "padding": [ "horizontal", "vertical" ]
        }
    }
}

Options:

Individual sides: top, right, bottom, left
Axial pairs: horizontal, vertical

Block Gap

{
    "supports": {
        "spacing": {
            "blockGap": true
        }
    }
}

blockGap only works on blocks that also use the layout support.

Real Example: Group Block

From packages/block-library/src/group/block.json:

{
    "supports": {
        "spacing": {
            "margin": [ "top", "bottom" ],
            "padding": true,
            "blockGap": true,
            "__experimentalDefaultControls": {
                "padding": true,
                "blockGap": true
            }
        }
    }
}

Typography Support

typography

object

Enables font-size, line-height, and other text controls

Line Height

{
    "supports": {
        "typography": {
            "lineHeight": true
        }
    }
}

Adds:

style.typography.lineHeight attribute

Text Alignment

Available since WordPress 6.6

{
    "supports": {
        "typography": {
            "textAlign": true  // All options: left, center, right
        }
    }
}

Or limit to specific alignments:

{
    "supports": {
        "typography": {
            "textAlign": [ "left", "right" ]
        }
    }
}

Real Example: Button Block

From packages/block-library/src/button/block.json:

{
    "supports": {
        "typography": {
            "fontSize": true,
            "lineHeight": true,
            "textAlign": true,
            "__experimentalFontFamily": true,
            "__experimentalFontWeight": true,
            "__experimentalFontStyle": true,
            "__experimentalTextTransform": true,
            "__experimentalTextDecoration": true,
            "__experimentalLetterSpacing": true,
            "__experimentalDefaultControls": {
                "fontSize": true
            }
        }
    }
}

Border Support

__experimentalBorder

object

Enables border color, radius, style, and width controls

{
    "supports": {
        "__experimentalBorder": {
            "color": true,
            "radius": true,
            "style": true,
            "width": true,
            "__experimentalDefaultControls": {
                "color": true,
                "radius": true,
                "style": true,
                "width": true
            }
        }
    }
}

From packages/block-library/src/paragraph/block.json:

{
    "supports": {
        "__experimentalBorder": {
            "color": true,
            "radius": true,
            "style": true,
            "width": true
        }
    }
}

Dimensions Support

Available since WordPress 6.2

dimensions

object

Controls for width, height, min-height, and aspect-ratio

{
    "supports": {
        "dimensions": {
            "aspectRatio": true,
            "height": true,
            "minHeight": true,
            "width": true
        }
    }
}

Stores values in:

attributes: {
    style: {
        dimensions: {
            aspectRatio: "16/9",
            height: "40vh",
            minHeight: "50vh",
            width: "400px"
        }
    }
}

Alignment Support

align

boolean | array

Enable block alignment controls

{
    "supports": {
        "align": true  // All options: left, center, right, wide, full
    }
}

Or specific alignments:

{
    "supports": {
        "align": [ "left", "right", "full" ]
    }
}

Adds align attribute automatically. From packages/block-library/src/paragraph/block.json:

{
    "supports": {
        "align": [ "wide", "full" ]
    }
}

Layout Support

layout

boolean | object

For container blocks with inner blocks

{
    "supports": {
        "layout": {
            "allowSwitching": true,
            "allowEditing": true,
            "allowInheriting": true,
            "default": {
                "type": "flex",
                "flexWrap": "nowrap"
            }
        }
    }
}

Layout Types

flow - Default vertical stacking
flex - Flexbox layout
constrained - Centered content with max-width

Real Example: Columns Block

From packages/block-library/src/columns/block.json:

{
    "supports": {
        "layout": {
            "allowSwitching": false,
            "allowInheriting": false,
            "allowEditing": false,
            "default": {
                "type": "flex",
                "flexWrap": "nowrap"
            }
        }
    }
}

Anchor Support

anchor

boolean

default:"false"

Allows users to define a custom HTML anchor/ID

{
    "supports": {
        "anchor": true
    }
}

Adds anchor attribute and UI field for setting an ID.

HTML Editing

html

boolean

default:"true"

Allow editing block markup as HTML

{
    "supports": {
        "html": false  // Disable HTML editing
    }
}

Multiple Instances

multiple

boolean

default:"true"

Allow inserting block more than once

{
    "supports": {
        "multiple": false  // Block can only be used once per post
    }
}

Reusable

reusable

boolean

default:"true"

Allow converting to a reusable block

{
    "supports": {
        "reusable": false
    }
}

Inserter Visibility

inserter

boolean

default:"true"

Show block in the inserter

{
    "supports": {
        "inserter": false  // Hide from inserter (programmatic use only)
    }
}

Class Name

className

boolean

default:"true"

Add automatic .wp-block-namespace-name class

{
    "supports": {
        "className": false  // Disable automatic class name
    }
}

Custom Class Name

customClassName

boolean

default:"true"

Allow users to add custom CSS classes

{
    "supports": {
        "customClassName": false
    }
}

Lock Support

lock

boolean

default:"true"

Allow users to lock/unlock the block

{
    "supports": {
        "lock": false  // Disable lock UI
    }
}

Renaming

Available since WordPress 6.5

renaming

boolean

default:"true"

Allow users to rename the block

{
    "supports": {
        "renaming": false
    }
}

Position Support

Available since WordPress 6.2

{
    "supports": {
        "position": {
            "sticky": true
        }
    }
}

Stores values in:

style: {
    position: {
        type: "sticky",
        top: "0px"
    }
}

Shadow Support

Available since WordPress 6.5

{
    "supports": {
        "shadow": true
    }
}

Stores value in style.shadow attribute.

Background Support

Available since WordPress 6.5

{
    "supports": {
        "background": {
            "backgroundImage": true,
            "backgroundSize": true,
            "__experimentalDefaultControls": {
                "backgroundImage": true
            }
        }
    }
}

Stores in:

style: {
    background: {
        backgroundImage: {
            url: "IMAGE_URL",
            id: 123,
            source: "file",
            title: "Image Title"
        },
        backgroundPosition: "50% 50%",
        backgroundSize: "cover"
    }
}

Interactivity API

interactivity

boolean | object

Indicates Interactivity API compatibility

{
    "supports": {
        "interactivity": {
            "clientNavigation": true,
            "interactive": true
        }
    }
}

Or simply:

{
    "supports": {
        "interactivity": true  // Both clientNavigation and interactive
    }
}

Combining Multiple Supports

Real-world example from the core Paragraph block:

{
    "supports": {
        "align": [ "wide", "full" ],
        "anchor": true,
        "className": false,
        "__experimentalBorder": {
            "color": true,
            "radius": true,
            "style": true,
            "width": true
        },
        "color": {
            "gradients": true,
            "link": true,
            "__experimentalDefaultControls": {
                "background": true,
                "text": true
            }
        },
        "spacing": {
            "margin": true,
            "padding": true,
            "__experimentalDefaultControls": {
                "margin": false,
                "padding": false
            }
        },
        "typography": {
            "fontSize": true,
            "lineHeight": true,
            "textAlign": true,
            "__experimentalFontFamily": true,
            "__experimentalFontWeight": true,
            "__experimentalLetterSpacing": true,
            "__experimentalDefaultControls": {
                "fontSize": true
            }
        },
        "interactivity": {
            "clientNavigation": true
        }
    }
}

Accessing Support Values

Check if a block supports a feature:

import { hasBlockSupport, getBlockSupport } from '@wordpress/blocks';

// Check if block supports colors
if ( hasBlockSupport( 'core/paragraph', 'color' ) ) {
    // Block supports colors
}

// Get the color support value
const colorSupport = getBlockSupport( 'core/paragraph', 'color' );
console.log( colorSupport );
// { gradients: true, link: true, __experimentalDefaultControls: {...} }

Best Practices

Use supports instead of custom attributes

Leverage block supports for common features rather than implementing custom attributes and controls.

Set default controls

Use __experimentalDefaultControls to show important controls by default while hiding advanced options.

Combine related supports

Consider theme compatibility

Some supports require theme opt-in via theme.json. Document any theme requirements for your blocks.

Overview

Getting Started

Core Concepts

Block Development

Advanced Guides

​How Block Supports Work

​Color Support

​Background Color

​Text Color

​Gradients

​Link, Heading, and Button Colors

​Real Example: Paragraph Block

​Spacing Support

​Margin and Padding

​Specific Sides

​Block Gap

​Real Example: Group Block

​Typography Support

​Font Size

​Line Height

​Text Alignment

​Real Example: Button Block

​Border Support

​Dimensions Support

​Alignment Support

​Layout Support

​Layout Types

​Real Example: Columns Block

​Anchor Support

​HTML Editing

​Multiple Instances

​Reusable

​Inserter Visibility

​Class Name

​Custom Class Name

​Lock Support

​Renaming

​Position Support

​Shadow Support

​Background Support

​Interactivity API

​Combining Multiple Supports

​Accessing Support Values

​Best Practices

​Next Steps

Block Patterns

Inner Blocks

Build docs developers (and LLMs) love

How Block Supports Work

Color Support

Background Color

Text Color

Gradients

Link, Heading, and Button Colors

Real Example: Paragraph Block

Spacing Support

Margin and Padding

Specific Sides

Block Gap

Real Example: Group Block

Typography Support

Font Size

Line Height

Text Alignment

Real Example: Button Block

Border Support

Dimensions Support

Alignment Support

Layout Support

Layout Types

Real Example: Columns Block

Anchor Support

HTML Editing

Multiple Instances

Reusable

Inserter Visibility

Class Name

Custom Class Name

Lock Support

Renaming

Position Support

Shadow Support

Background Support

Interactivity API

Combining Multiple Supports

Accessing Support Values

Best Practices

Next Steps