---
tags:
  - wordpress
  - fse
  - theme.json
  - block-styles
  - css
title: Registering Custom Block Styles via theme.json
---

# 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`.

```json
"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:
1.  **"Shadow"**: Adds a heavy drop shadow.
2.  **"Polaroid"**: Adds a white border and a shadow.

Open your `theme.json`:

```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:
1.  WordPress adds the class `is-style-polaroid` to the `<figure>` element of the image block.
2.  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.