Understanding Spacing Presets vs. Raw Values in theme.json

In WordPress FSE, spacing (padding, margin, blockGap) is handled by a "Scale" system. Unlike settings.custom, spacing variables are strictly tied to the settings.spacing.spacingSizes array.

1. The Mapping Logic

When you define a spacing size, WordPress generates a CSS variable based on the slug.

Syntax Formula: --wp--preset--spacing--{slug}

Example Configuration

{
    "version": 3,
    "settings": {
        "spacing": {
            "spacingSizes": [
                { "name": "Small", "slug": "20", "size": "1.5rem" },
                { "name": "Medium", "slug": "40", "size": "2.5rem" },
                { "name": "Large", "slug": "60", "size": "4rem" }
            ]
        }
    }
}

2. Generated CSS Output

WordPress automatically registers these in the :root or body of both the frontend and the editor:

:root {
    --wp--preset--spacing--20: 1.5rem;
    --wp--preset--spacing--40: 2.5rem;
    --wp--preset--spacing--60: 4rem;
}

3. Usage: Preset vs. Raw

You have two ways to apply spacing in the styles section of your theme.json.

A. Using the Preset (Recommended)

This keeps your design locked to your defined scale. If you update the "40" slug in settings, every block using it updates automatically.

"core/group": {
    "spacing": {
        "padding": { 
            "top": "var(--wp--preset--spacing--40)", 
            "bottom": "var(--wp--preset--spacing--40)" 
        }
    }
}

B. Using Raw Values (The "Wild West")

You can bypass the scale entirely by passing a direct CSS value (px, rem, em). This is useful for one-off layouts that don't fit your standard scale.

"core/group": {
    "spacing": {
        "padding": { 
            "top": "100px", 
            "bottom": "5vh" 
        }
    }
}

4. The `spacingScale` Gotcha

If you define a spacingScale (e.g., "steps": 5) but also provide a manual spacingSizes array:

Manual wins: WordPress will only generate variables for the slugs you explicitly listed in the array.
Missing Slugs: Referencing a variable like --wp--preset--spacing--50 will fail if "50" isn't in your manual list, even if your scale says it should exist.

5. Summary Table

Method	Syntax	Pros	Cons
Preset Variable	`var(--wp--preset--spacing--40)`	Scalable, centralized, theme-aware.	Fails if slug is missing in settings.
Raw Value	`2.5rem` or `40px`	Fast, works anywhere, no setup.	Harder to maintain; bypasses global design rules.

Would you like me to update your actual theme.json with a more complete 10-step spacing scale so you have more presets to choose from?

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

Docs Login