I recently wrote about block variations and block styles, styles associated with a core block that appear when you add a block to your page or post. Common examples are button style variations like “Default,” “Outline,” or other block styles that may be included in your theme.
Introducing Section Styles
Section Styles are an extension of block styles and they work with any block that supports inner blocks (groups, columns, covers, etc). The main advantage and use case for Section Styles is that you can create curated design presets for entire “sections” of your pages. And, as with block styles, Section Styles are only loaded when the section exists resulting in better performance.
Helpful, curated design defaults for everyone
Section Styles provide helpful defaults and design consistency without limiting the user from making adjustments. Your section style might set heading colors to blue, but users can change individual headings through the block editor without any conflicts. This flexibility works because WordPress keeps CSS specificity low by “using :where() but prefixing it with :root. The result is selectors with 0-1-0 specificity.”
Section style or pattern?
Section Styles and Patterns serve different purposes.
Patterns provide complete content structures: the blocks, placeholder content, and initial layout. They’re great when you want to give users a starting point with a specific content arrangement. With Patterns, we also have the ability to make a design synced or partially synced with pattern overrides.
Section Styles are more open ended, separating content and style through visual treatments that work across different content structures. They’re especially useful when you want consistent styling options that users can apply to any content they’re building, without dictating the structure.
For example, you might have a “Feature Section” style that allows for a two-column layout with an image and text. But what if users want that same visual treatment (background color, heading style, button appearance) for a three-column layout? Or a stacked group with a different heading structure? Section styles let them apply visual design presets to any Group, Cover, or Columns block, regardless of what’s inside.
It’s possible to flesh (section styles) out to include styles for every element and block that WordPress supports, styling them when they are used within this block. It’s for this reason that these types of variations may best be used for container-type blocks, such as Group, Columns, and Cover.
Justin Tadlock, Styling Sections… (2024)
Section styles work well when:
- You want to provide multiple visual options (light background, dark background, accent color) without creating separate patterns for every possible variation
- Content structures may vary too much to use patterns, but you still want visual consistency
- Users need flexibility to build their own layouts but don’t want to think about every little design choice
- You want to update a visual treatment site-wide by editing one file rather than managing pattern instances
Creating section styles
Like Global Style Variations or JSON block styles, Section Styles are created in the /styles/ directory at the root of your theme:
your-theme/
├── theme.json
└── styles/
├── spotlight-left.json
├── section-contrast.json
└── hero-banner.json
As of 6.0, WordPress automatically discovers any JSON files in this directory and registers them as available block styles. You don’t need to register them in functions.php or add any PHP code. Note that "version": 3 is required.
Each file contains a complete style definition. Here’s my working example:
{
"$schema": "https://schemas.wp.org/wp/6.9/theme.json",
"version": 3,
"title": "Spotlight Left",
"slug": "spotlight-left",
"blockTypes": ["core/group", "core/columns"],
"styles": {
"color": {
"background": "var:preset|color|primary",
"text": "var:preset|color|background"
},
"spacing": {
"padding": {
"top": "var:preset|spacing|medium",
"right": "var:preset|spacing|medium",
"bottom": "var:preset|spacing|medium",
"left": "var:preset|spacing|medium"
}
},
"elements": {
"heading": {
"color": {
"text": "var:preset|color|secondary"
}
}
}
}
}
The filename can be anything, though it’s helpful to prefix with ‘section-‘ for easy identification. Inside your JSON file, the title and slug should match. The title is what users see in the editor, and the slug is the internal identifier.
Ollie’s theme academy has an excellent how-to video to get you started, Creating a Section Style.
Unknown unknowns
I think that there are limitations to what is allowed in Section Style JSON but I’m having a hard time finding specific documentation around this.
Limitations that I am aware of (not necessarily complete or correct):
- Section Styles are limited to styles – you can’t add settings here
- You can style elements per Section Style, but you can’t style a block style variation of an element (ex. Button with the outline style) with the Section Style
- Each Section Style needs it’s own separate JSON file inside the theme’s /styles/ directory
- Spacing values DO work but blockGap – for gap spacing – does NOT work
- Alignment and justification not available here
- User’s block style adjustments will override the Section Style presets (by design, specificity here is low)
- Preset values aren’t visible to the user (known issue) – so, even though there may be padding or colors in use, those aren’t displayed in the styles panel
If you know more, please comment!
JSON structure and syntax
WordPress supports shorthand or CSS variables in your section styles:
CSS variable format:
"color": {
"background": "var(--wp--preset--color--primary)"
}Shorthand format:
"color": {
"background": "var:preset|color|primary"
}The shorthand is a bit easier to read and quicker to edit if you are using presets.
If you are using the css property to add custom CSS that theme.json doesn’t directly support, you will need to use full CSS (or full CSS variable) inside that string:
"css": "background-color: var(--wp--preset--color--primary);"
This is because the css property outputs raw CSS to your stylesheet, and WordPress doesn’t process shorthand syntax in these strings.
Adapting the section style of a parent theme
Child themes can add new section styles or override parent section styles.
- To add a new style: Create a file with a unique slug in your child theme’s
/styles/directory. Both the parent’s styles and your new styles will be available. - To override a parent style: Create a new JSON file in your
/styles/directory using the same filename, title, and slug as the parent theme. Your child theme version will override the parent’s version entirely.
Sometimes, when you create a child theme, your custom palette may be applied in unexpected and ungainly ways to parent section styles (patterns as well) and you’ll want to refine these. An override is useful in this case but be aware that you’re completely replacing it, not just modifying parts of it.
Troubleshooting issues:
- Mismatched filename and slug when overriding a parent section style
- I started a new section-primary.json file in my /styles/ folder to override the parent section style. But I forgot to match the title and slug to the parent even through the filename DID match. As a result, neither the parent nor the child section style showed up. Double-check the obvious human errors like naming and syntax (ie. Try turning it off and then on again).
- JSON syntax errors
- Missing commas, extra commas, or unclosed brackets will break your entire style file. WordPress can’t parse invalid JSON, so the style simply won’t appear.
- Incorrect property nesting
- Some properties need specific nesting structures. For example, heading color must be nested inside a color object:
// Correct
"heading": {
"color": {
"text": "var:preset|color|secondary"
}
}
// Oops!
"heading": {
"text": "var:preset|color|secondary"
}
The theme.json reference on WordPress.org is helpful when you’re not sure about the correct structure for a property.
Limitations and appropriate control
The main caveat with section styling is that it is easy to get carried away and add too many style options for group blocks and columns. Here we need to practice restraint to not overwhelm users.
Carolina Nymark, FullSiteEditing.com
Section styles should control the container and set sensible defaults for common elements. Content editors should retain full control over the blocks they place inside. If you find yourself writing complex CSS to control every aspect of the inner content, you might be better off with a synced or partially-synced pattern.
Section Styles are a really cool tool for your Block Theme toolbox. If you’re not using them yet, what are you waiting for?
Resources
- Carolina Nymark wrote about the difference between block styles, section styles, and global style variations
- In this in depth tutorial, Brian Coords explains Section Styles (introduced) in WordPress 6.6 (video)
- Justin Tadlock on Styling Sections, Nested Elements via the WordPress Developer Blog
- WordPress CSS Specificity – “WordPress 6.6 introduces several changes aimed at broadly reducing CSS specificity and making it more uniform.”
- Creating a Section Style, via Ollie Theme Academy (Video)
