How to Use Style Variations in WordPress Block Themes?

A client likes the layout of their block theme but wants it darker for the holiday season, or a designer wants to offer three color schemes and two font pairings without shipping five separate themes. In the classic era, that meant a stack of Customizer options and a lot of conditional CSS. Block themes solve it with style variations: JSON files in the theme that swap colors, fonts, spacing, and block styles in one click from the Site Editor, with no code running on the front end beyond the CSS WordPress already generates.

This article covers the three kinds of style variations in current WordPress, how users apply them in the Site Editor, how to build each kind as a theme developer, how to register block style variations with PHP, and how to fix the problems that make variations fail to appear. The examples use theme.json version 3 and match WordPress 7.1.

The Three Kinds of Style Variations

"Style variation" is used for three related features. All of them live as JSON files in the theme's styles folder, and WordPress tells them apart by what the file contains.

Kind	What it changes	How WordPress recognizes it	Where users pick it
Theme style variation	Anything in theme.json: colors, fonts, spacing, block styles	A file with settings or styles of more than one kind	Styles → Browse styles
Color or typography preset	Only the color palette, or only font families and sizes	A file whose settings and styles are limited to color, or to typography	Styles → Colors → Palette, Styles → Typography
Block style variation (section style)	The look of a specific block, including its inner blocks	A file with a blockTypes key	The Styles panel in the block sidebar

Color and typography presets arrived in WordPress 6.6, together with section styles, the JSON-based version of block style variations. Before that, every file in styles was a full theme variation.

The default theme Twenty Twenty-Five is the best real-world reference. Its styles folder contains eight full variations at the top level and four subfolders:

twentytwentyfive/styles/
├── 01-evening.json
├── 02-noon.json
├── ...
├── 08-midnight.json
├── blocks/        # block style variations for headings, paragraphs, post terms
├── colors/        # color-only presets
├── sections/      # section styles for Group, Columns, and Column blocks
└── typography/    # typography-only presets

The subfolders are for organization. WordPress scans the styles folder recursively and classifies each file by its content, not by its folder name: a file with blockTypes is a block style variation, and the editor treats a file that contains only color values, or only typography values, as a preset.

Applying a Style Variation in the Site Editor

For site owners, using variations takes a few clicks:

1. Go to Appearance → Editor.
2. Click Styles in the sidebar.
3. Click Browse styles to see each full variation previewed as a card. Click one to apply it to the canvas.
4. To change only the colors, open Colors → Palette and pick one of the color presets. To change only the fonts, open Typography and pick a typography preset.
5. Click Save.

The choice is stored in the site's global styles, the wp_global_styles post that also holds any manual changes you make in the Styles panel. That has two consequences:

• Variations are not live theme files. Applying a variation copies its values into global styles. If the theme author later changes the variation file, your site keeps the values it saved until you apply the variation again.
• Global styles are per theme. Switching to another theme and back restores the saved global styles for the original theme, but they never carry over to a different theme.

To return to the theme's default look, open the three-dot menu in the Styles panel and choose Reset styles, or review earlier versions under Revisions before deciding.

Applying Block Style Variations

Block style variations show up per block, not in the global Styles screen:

1. Select a block in the editor, such as a Group block.
2. In the block sidebar, open the Styles tab.
3. Click one of the style options. Twenty Twenty-Five, for example, offers Style 1 through Style 5 for Group blocks, each with its own background, text, and button colors.

WordPress adds a class such as is-style-section-1 to the block, and the generated CSS styles the block and its nested blocks.

Creating a Theme Style Variation

A theme style variation is a partial theme.json. It contains only the values that differ from the theme's root theme.json, and WordPress merges it on top.

Create wp-content/themes/my-theme/styles/midnight.json:

{
  "$schema": "https://schemas.wp.org/wp/7.1/theme.json",
  "version": 3,
  "title": "Midnight",
  "settings": {
    "color": {
      "palette": [
        { "slug": "base", "name": "Base", "color": "#0f172a" },
        { "slug": "contrast", "name": "Contrast", "color": "#e2e8f0" },
        { "slug": "accent", "name": "Accent", "color": "#38bdf8" }
      ]
    }
  },
  "styles": {
    "color": {
      "background": "var:preset|color|base",
      "text": "var:preset|color|contrast"
    },
    "typography": {
      "lineHeight": "1.7"
    },
    "elements": {
      "link": {
        "color": { "text": "var:preset|color|accent" }
      },
      "button": {
        "color": {
          "background": "var:preset|color|accent",
          "text": "var:preset|color|base"
        }
      }
    },
    "blocks": {
      "core/separator": {
        "color": { "text": "var:preset|color|accent" }
      }
    }
  }
}

Key points:

• version must match the schema version your theme uses. Use 3 for current themes.
• title is the name shown in the Browse styles screen. It is optional, but without it WordPress falls back to the file name.
• Keep palette slugs identical across variations. Templates and patterns reference colors by slug, such as var:preset|color|accent. If every variation defines base, contrast, and accent, every template works with every variation. If one variation renames accent to highlight, blocks using accent lose their color.
• Include only what changes. This variation overrides colors and line height. Fonts, spacing, and layout come from the root theme.json.

Because this file changes both color and typography, WordPress treats it as a full theme variation rather than a color preset.

Twenty Twenty-Five prefixes its file names with numbers, such as 01-evening.json, to control the order of the cards in the Browse styles screen. You can use the same convention.

Creating Color and Typography Presets

Presets let users mix and match. Instead of shipping six full variations for every combination of three palettes and two font pairs, you ship three color presets and two typography presets.

A Color Preset

A file becomes a color preset when its settings and styles contain only color-related values. Create styles/colors/forest.json:

{
  "$schema": "https://schemas.wp.org/wp/7.1/theme.json",
  "version": 3,
  "title": "Forest",
  "settings": {
    "color": {
      "palette": [
        { "slug": "base", "name": "Base", "color": "#f4f1ea" },
        { "slug": "contrast", "name": "Contrast", "color": "#1f2a1f" },
        { "slug": "accent", "name": "Accent", "color": "#2f6b3a" }
      ]
    }
  },
  "styles": {
    "color": {
      "background": "var:preset|color|base",
      "text": "var:preset|color|contrast"
    }
  }
}

This preset appears under Styles → Colors → Palette. Applying it swaps the palette and color styles while leaving the user's font choices alone.

A Typography Preset

A typography preset contains only typography values. Create styles/typography/editorial.json:

{
  "$schema": "https://schemas.wp.org/wp/7.1/theme.json",
  "version": 3,
  "title": "Editorial",
  "slug": "editorial",
  "settings": {
    "typography": {
      "fontFamilies": [
        {
          "name": "Literata",
          "slug": "body",
          "fontFamily": "Literata, Georgia, serif",
          "fontFace": [
            {
              "fontFamily": "Literata",
              "fontWeight": "200 900",
              "fontStyle": "normal",
              "src": ["file:./assets/fonts/literata/Literata-Variable.woff2"]
            }
          ]
        },
        {
          "name": "Inter",
          "slug": "heading",
          "fontFamily": "Inter, system-ui, sans-serif",
          "fontFace": [
            {
              "fontFamily": "Inter",
              "fontWeight": "100 900",
              "fontStyle": "normal",
              "src": ["file:./assets/fonts/inter/Inter-Variable.woff2"]
            }
          ]
        }
      ]
    }
  },
  "styles": {
    "typography": {
      "fontFamily": "var:preset|font-family|body"
    },
    "elements": {
      "heading": {
        "typography": {
          "fontFamily": "var:preset|font-family|heading",
          "fontWeight": "700"
        }
      }
    }
  }
}

Two details matter here:

• Font file paths are relative to the theme root, not to the JSON file. file:./assets/fonts/... points to my-theme/assets/fonts/... even though the preset lives two folders deeper.
• Use role-based slugs, such as body and heading, across all typography presets. The styles then always reference body and heading, and each preset just changes which font those roles use.

Font registration in theme.json, including subsets and variable fonts, is covered in how to change fonts in a WordPress block theme using theme.json.

Creating Block Style Variations and Section Styles

Block style variations change one block type. Section styles are block style variations for container blocks such as Group and Columns, and they can style the blocks nested inside them. That makes them ideal for alternating page sections: a dark band with light text and inverted buttons, followed by a light band with an accent border.

A file becomes a block style variation when it has a blockTypes key. Create styles/sections/section-dark.json:

{
  "$schema": "https://schemas.wp.org/wp/7.1/theme.json",
  "version": 3,
  "title": "Dark Section",
  "slug": "section-dark",
  "blockTypes": ["core/group", "core/columns", "core/column"],
  "styles": {
    "color": {
      "background": "var:preset|color|contrast",
      "text": "var:preset|color|base"
    },
    "spacing": {
      "padding": {
        "top": "var:preset|spacing|60",
        "bottom": "var:preset|spacing|60"
      }
    },
    "elements": {
      "heading": {
        "color": { "text": "var:preset|color|base" }
      },
      "link": {
        "color": { "text": "currentColor" }
      },
      "button": {
        "color": {
          "background": "var:preset|color|base",
          "text": "var:preset|color|contrast"
        }
      }
    },
    "blocks": {
      "core/separator": {
        "color": { "text": "var:preset|color|accent" }
      }
    }
  }
}

The slug becomes the class name, so this section style adds is-style-section-dark. The blockTypes array lists every block that should offer the style. The elements and blocks keys style headings, links, buttons, and separators inside the section, which is what makes section styles more powerful than older block styles that only changed the outer block.

A simpler block style variation, for text blocks, follows the same format. This one creates a small uppercase eyebrow label for headings and paragraphs:

{
  "$schema": "https://schemas.wp.org/wp/7.1/theme.json",
  "version": 3,
  "title": "Eyebrow",
  "slug": "text-eyebrow",
  "blockTypes": ["core/heading", "core/paragraph"],
  "styles": {
    "typography": {
      "fontSize": "var:preset|font-size|small",
      "fontWeight": "600",
      "letterSpacing": "0.08em",
      "textTransform": "uppercase"
    },
    "color": {
      "text": "var:preset|color|accent"
    }
  }
}

Adjusting Section Styles per Color Preset

A dark section that looks right with one palette may clash with another. Color presets and full variations can override a section style through styles.variations, keyed by the section style's slug. Twenty Twenty-Five uses this in its color presets. Add the override to styles/colors/forest.json:

{
  "$schema": "https://schemas.wp.org/wp/7.1/theme.json",
  "version": 3,
  "title": "Forest",
  "settings": {
    "color": {
      "palette": [
        { "slug": "base", "name": "Base", "color": "#f4f1ea" },
        { "slug": "contrast", "name": "Contrast", "color": "#1f2a1f" },
        { "slug": "accent", "name": "Accent", "color": "#2f6b3a" }
      ]
    }
  },
  "styles": {
    "variations": {
      "section-dark": {
        "color": {
          "background": "var:preset|color|accent",
          "text": "var:preset|color|base"
        }
      }
    }
  }
}

With the Forest palette active, dark sections use the green accent as their background instead of the near-black contrast color.

Registering Block Styles with PHP

You can also register block style variations in PHP. Since WordPress 6.6, register_block_style() accepts an array of block types and a style_data argument that takes the same structure as the JSON styles object. This is useful in plugins, or when a variation should only be registered under certain conditions.

<?php
// wp-content/themes/my-theme/functions.php
add_action( 'init', 'mytheme_register_block_styles' );

function mytheme_register_block_styles() {
register_block_style(
array( 'core/group', 'core/columns' ),
array(
  'name'       => 'section-outlined',
  'label'      => __( 'Outlined Section', 'my-theme' ),
  'style_data' => array(
    'border'  => array(
      'color'  => 'var:preset|color|accent',
      'width'  => '2px',
      'style'  => 'solid',
      'radius' => '12px',
    ),
    'spacing' => array(
      'padding' => array(
        'top'    => 'var:preset|spacing|50',
        'right'  => 'var:preset|spacing|50',
        'bottom' => 'var:preset|spacing|50',
        'left'   => 'var:preset|spacing|50',
      ),
    ),
  ),
)
);
}

WordPress generates the CSS from style_data, scoped to .is-style-section-outlined, so you do not need a stylesheet. For the older approach with inline_style or style_handle, and for JavaScript registration with registerBlockStyle, see the block style variations reference listed at the end of this article.

Building a Variation from the Site Editor

You do not have to write variation JSON by hand. A practical workflow for designers:

1. Start from the theme's default look on a local or staging site.
2. Use Appearance → Editor → Styles to adjust colors, typography, and block styles until the new look is right.
3. Install the Create Block Theme plugin and use its option to save the current styles as a new style variation. It writes a JSON file into the theme's styles folder.
4. Reset the global styles so the site returns to the default look, then check that the new variation appears under Browse styles.
5. Open the generated file and remove anything that duplicates the root theme.json, so the variation contains only real differences.

Commit the resulting files to version control like any other theme code.

Using Variations in a Child Theme

Style variations work in child themes as well. Since WordPress 6.2, a child theme inherits the parent theme's variations, and it can add its own files to a styles folder. If a child theme file has the same file name as a parent variation, only the child's version is used. That makes a child theme a clean way to add a brand palette to a third-party block theme without editing the parent. The general approach is described in creating and customizing WordPress child themes.

Common Problems and Fixes

• The variation does not appear in Browse styles. Validate the JSON; a trailing comma silently stops WordPress from loading the file. Then confirm the file sits inside the theme's styles folder and that version matches the theme.
• A color preset shows up as a full variation. It contains non-color values, such as a font size or spacing. Move those values into a separate typography preset or the root theme.json.
• A section style does not appear in the block sidebar. The file is missing blockTypes or styles, or the block you selected is not in the blockTypes list. Both keys are required.
• Fonts in a typography preset do not load. The file: path is wrong. Paths start from the theme root, so use file:./assets/fonts/... regardless of where the preset file lives.
• Some blocks lose their color after switching variations. The variations use different palette slugs. Use the same slugs in every variation and change only the color values.
• Updates to a variation file do not reach the live site. The site saved the variation's values into global styles. Apply the variation again from Browse styles to pick up the new values.
• Manual style changes disappeared after picking a variation. Applying a variation replaces the related global style values. Check Styles → Revisions to restore the previous state.

WordPress Style Variations FAQ

Conclusion

Style variations turn one block theme into several looks without extra templates or code. Full theme variations swap the entire design, color and typography presets let users mix palettes and font pairings independently, and section styles give container blocks complete, reusable treatments that reach down into headings, links, and buttons.

The rules are simple once you know them. Keep every variation as a small partial of theme.json, keep palette and font slugs consistent across variations, add blockTypes and a slug for block-level styles, and remember that applying a variation copies its values into the site's global styles. Build variations visually with the Site Editor and Create Block Theme when that is faster, then keep the resulting JSON in version control with the rest of the theme.

Here are some useful references for going deeper on style variations:

1. WordPress Developer Resources: Style Variations — the theme handbook's guide to variation files.
2. WordPress Developer Resources: Block Style Variations — registering block styles with PHP, JavaScript, and theme.json.
3. WordPress Developer Resources: register_block_style() — function reference, including the style_data argument.
4. WordPress Documentation: Styles Overview — how users browse and apply styles in the Site Editor.
5. WordPress.org Themes: Twenty Twenty-Five — a default theme with full variations, presets, and section styles to study.