Registering Custom Block Styles via theme.json

In the past, adding a custom "Style" to a block (which appears in the "Styles" section of the block sidebar) required PHP code using register_block_style().

As of WordPress 6.6 (Schema Version 3), you can register these styles directly in theme.json without writing any PHP or JavaScript.

1. The Concept

Block Styles allow users to toggle between different visual variations of a block.

Example: A Button block might have "Fill" (default) and "Outline" styles.
Mechanism: Selecting a style adds a CSS class (e.g., .is-style-outline) to the block wrapper.

2. The Structure

You define these inside styles.blocks.[block-name].variations.

"styles": {
    "blocks": {
        "core/image": {
            "variations": [
                {
                    "name": "polaroid",
                    "label": "Polaroid",
                    "style": { ... }
                }
            ]
        }
    }
}

name: The slug. This generates the class .is-style-{name}.
label: The human-readable name shown in the Editor sidebar.
style: The CSS properties to apply when this style is selected.

3. Practical Example: Image Block Styles

Let's create two custom styles for the Image block:

"Shadow": Adds a heavy drop shadow.
"Polaroid": Adds a white border and a shadow.

Open your theme.json:

{
    "version": 3,
    "styles": {
        "blocks": {
            "core/image": {
                "variations": [
                    {
                        "name": "shadow-hard",
                        "label": "Hard Shadow",
                        "style": {
                            "shadow": "10px 10px 0px #000000"
                        }
                    },
                    {
                        "name": "polaroid",
                        "label": "Polaroid",
                        "style": {
                            "border": {
                                "width": "15px",
                                "color": "#ffffff",
                                "style": "solid",
                                "radius": "0px"
                            },
                            "shadow": "0px 4px 20px rgba(0,0,0,0.15)"
                        }
                    }
                ]
            }
        }
    }
}

4. Under the Hood

When a user selects "Polaroid" in the editor:

WordPress adds the class is-style-polaroid to the <figure> element of the image block.
WordPress automatically generates the CSS for that class based on the style object you provided and injects it into the page.

5. Limitations

Complex Selectors: You cannot write arbitrary CSS selectors (like :before or & > img) easily inside the style object. For complex pseudo-elements, you still need to load a separate CSS file and target .is-style-polaroid manually.
Elements: However, you can use the elements nested object if you need to style links or headings inside that specific block style variation.

Created: March 19, 2026 • Last Modified: March 19, 2026

Docs Login