Title: Section Styles
Author: Aaron Robertshaw
Published: June 24, 2024

---

 [  ](https://profiles.wordpress.org/aaronrobertshaw/) [Aaron Robertshaw](https://profiles.wordpress.org/aaronrobertshaw/)
11:29 am _on_ June 24, 2024     
Tags: [6-6 ( 57 )](https://make.wordpress.org/core/tag/6-6/),
[core-editor ( 764 )](https://make.wordpress.org/core/tag/core-editor/), [dev-notes ( 654 )](https://make.wordpress.org/core/tag/dev-notes/),
[dev-notes-6.6 ( 19 )](https://make.wordpress.org/core/tag/dev-notes-6-6/), [gutenberg ( 555 )](https://make.wordpress.org/core/tag/gutenberg/)

# Section Styles

In WordPress 6.6, [Section Styles](https://github.com/WordPress/gutenberg/issues/57537)
simplify the process of styling individual sections of a webpage by offering users
a one-click application of curated styles, eliminating the need for repetitive manual
configuration.

## Table of Contents

 1. [What’s Changed?](https://make.wordpress.org/core/2024/06/24/section-styles/?output_format=md#what-s-changed)
 2. [Usage](https://make.wordpress.org/core/2024/06/24/section-styles/?output_format=md#usage)
 3.  a. [Registration of Block Style Variations](https://make.wordpress.org/core/2024/06/24/section-styles/?output_format=md#registration-of-block-style-variations)
     b. [Defining Block Style Variations](https://make.wordpress.org/core/2024/06/24/section-styles/?output_format=md#defining-block-style-variations)
     c.  a. [Theme.json Partial Files](https://make.wordpress.org/core/2024/06/24/section-styles/?output_format=md#theme-json-partial-files)
         b. [Programmatically](https://make.wordpress.org/core/2024/06/24/section-styles/?output_format=md#programmatically)
         c. [Via Theme Style Variations (Not Recommended)](https://make.wordpress.org/core/2024/06/24/section-styles/?output_format=md#via-theme-style-variations-not-recommended)
 4. [Backwards Compatibility](https://make.wordpress.org/core/2024/06/24/section-styles/?output_format=md#backwards-compatibility)
 5. [Limitations](https://make.wordpress.org/core/2024/06/24/section-styles/?output_format=md#limitations)
 6. [What’s Next?](https://make.wordpress.org/core/2024/06/24/section-styles/?output_format=md#what-s-next)
 7. [Useful Links](https://make.wordpress.org/core/2024/06/24/section-styles/?output_format=md#useful-links)

## What’s Changed?

Section-based styling has been enabled by extending the existing [Block Styles](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-styles/)
feature (aka blockBlock Block is the abstract term used to describe units of markup
that, composed together, form the content or layout of a webpage using the WordPress
editor. The idea combines concepts of what in the past may have achieved with shortcodes,
custom HTML, and embed discovery into a single consistent API and user experience.
style variations) to support styling inner elements and blocks. These enhanced block
style variations can even be applied in a nested fashion due to [uniform CSS specificity](https://github.com/WordPress/gutenberg/pull/61638#issuecomment-2151295357)(`
0-1-0`) for Global Styles [introduced](https://github.com/WordPress/gutenberg/pull/61638)
in WP 6.6.

In addition block style variations can now be:

 * registered across multiple block types at the same time
 * defined via multiple methods; primarily through theme.jsonJSON JSON, or JavaScript
   Object Notation, is a minimal, readable format for structuring data. It is used
   primarily to transmit data between a server and web application, as an alternative
   to XML. partials, or by passing a theme.json shaped object in the style’s data
   given to existing block style registration functions
 * customized via Global Styles (see also current limitations)

## Usage

### Registration of Block Style Variations

The block style variations that can be defined and manipulated through Global Styles
are limited to those that have been registered with the `WP_Block_Styles_Registry`
or via a block type’s `styles` property, such as Outline for the Button block. If
a block style variation has not been registered, any theme.json or global styles
data for it will be stripped out.

Any unregistered block style variation defined within a theme.json partial with 
be automatically registered.

Outlined below are three approaches to registering extended block style variations.
The approaches leveraging theme.json definitions will automatically register the
block style variation with the `WP_Block_Styles_Registry`.

### Defining Block Style Variations

Outlined below are recommended approaches to registering extended block style variations.

#### Theme.json Partial Files

With the extension of block style variations to support inner element and block 
type styles, they essentially are their own theme.json file much like theme style
variations. As such, block style variations also reside under a theme’s `/styles`
directory. They are differentiated from theme style variations however by the introduction
of a new top-level property called `blockTypes`. The `blockTypes` property is an
array of block types the block style variation can be applied to.

A new `slug` property was also added to provide consistency between the different
sources that may define block style variations and to decouple the slug from the
translatable `title` property.

    ```notranslate
    {
    	"$schema": "https://schemas.wp.org/trunk/theme.json",
    	"version": 3,
    	"title": "Variation A",
    	"slug": "variation-a",
    	"blockTypes": [ "core/group", "core/columns", "core/media-text" ],
    	"styles": {
    		"color": {
    			"background": "#eed8d3",
    			"text": "#201819"
    		},
    		"elements": {
    			"heading": {
    				"color": {
    					"text": "#201819"
    				}
    			}
    		},
    		"blocks": {
    			"core/group": {
    				"color": {
    					"background": "#825f58",
    					"text": "#eed8d3"
    				},
    				"elements": {
    					"heading": {
    						"color": {
    							"text": "#eed8d3"
    						}
    					}
    				}
    			}
    		}
    	}
    }
    ```

#### Programmatically

Within a theme’s `functions.php` or a pluginPlugin A plugin is a piece of software
containing a group of functions that can be added to a WordPress website. They can
extend functionality or add new features to your WordPress websites. WordPress plugins
are written in the PHP programming language and integrate seamlessly with WordPress.
These can be free in the WordPress.org Plugin Directory [https://wordpress.org/plugins/](https://wordpress.org/plugins/)
or can be cost-based plugin from a third-party., a call can be made to `register_block_style`,
passing it an array of block types the variation can be used with as well as a theme.
json shaped style object defining the variation’s styles. The style object provided
here will be absorbed into the theme’s theme.json data.

    ```notranslate
    register_block_style(
    	array( 'core/group', 'core/columns' ),
    	array(
    		'name'       => 'green',
    		'label'      => __( 'Green' ),
    		'style_data' => array(
    			'color'    => array(
    				'background' => '#4f6f52',
    				'text'       => '#d2e3c8',
    			),
    			'blocks'   => array(
    				'core/group' => array(
    					'color' => array(
    						'background' => '#739072',
    						'text'       => '#e3eedd',
    					),
    				),
    			),
    			'elements' => array(
    				'link'   => array(
    					'color'  => array(
    						'text' => '#ead196',
    					),
    					':hover' => array(
    						'color' => array(
    							'text' => '#ebd9b4',
    						),
    					),
    				),
    			),
    		),
    	)
    )
    ```

#### Via Theme Style Variations (Not Recommended)

This approach has been enabled as a temporary means to facilitate ergonomic definitions
of shared block style variations through theme style variations. It is being flagged
here for transparency however it will likely be deprecated soon as the Global Styles
architecture is updated to address growing complexity and simplify its mental model.

More details on what’s ahead for Global Styles can be found in this [issue](https://github.com/WordPress/gutenberg/issues/62686).

Shared block style variations can be defined via `styles.variations`. Style data
defined under `styles.variations` will be copied to, and merged with, variation 
data stored at the block type level for all block types that have a matching variation
registered for it.

Additionally, a new translatable `title` property has been added here to mirror 
the capabilitiescapability A **capability** is permission to perform one or more
types of task. Checking if a user has a capability is performed by the `current_user_can`
function. Each user of a WordPress site might have some permissions but not others,
depending on their role. For example, users who have the Author role usually have
permission to edit their own posts (the “edit_posts” capability), but not permission
to edit other users’ posts (the “edit_others_posts” capability). of the theme.json
partial files outlined above.

The key for the variation correlates to the `slug` property for theme.json partials.
In the example below, this would be `variation-a`.

    ```notranslate
    {
    	"$schema": "https://schemas.wp.org/trunk/theme.json",
    	"version": 3,
    	"title": "Theme Style Variation",
    	"styles": {
    		"variations": {
    			"variation-a": {
    				"color": {
    					"background": "#eed8d3",
    					"text": "#201819"
    				},
    				"elements": {
    					"heading": {
    						"color": {
    							"text": "#201819"
    						}
    					},
    				},
    				"blocks": {
    					"core/group": {
    						"color": {
    							"background": "#825f58",
    							"text": "#eed8d3"
    						},
    						"elements": {
    							"heading": {
    								"color": {
    									"text": "#eed8d3"
    								}
    							}
    						}
    					}
    				}
    			},
    		}
    	}
    }
    ```

## Backwards Compatibility

As the Section Styles feature was implemented via extensions to block style variations
rather than as a replacement, existing block style variations will continue to work
as before.

## Limitations

The following limitations for block style variations in WordPress 6.6 should be 
noted:

 1. Only root styles, i.e. those that apply directly to the block type the block style
    variation belongs to, can be configured via Global Styles.
 2. Block style variations cannot redefine or customize inner block style variations.
 3. Block style variations do not support their own custom `settings` values (yet).
 4. Custom block style variations cannot be applied and previewed within the Style 
    Book.

## What’s Next?

The Global Styles UIUI User interface for block style variations will be updated
to facilitate the customization of all available styles for inner elements and block
types. This includes potentially enhancing the Style Book to support block style
variations.

Another future enhancementenhancement Enhancements are simple improvements to WordPress,
such as the addition of a hook, a new feature, or an improvement to an existing 
feature. is the possible support for settings per block style variations.

## Useful Links

 * [#57537](https://github.com/WordPress/gutenberg/issues/57537) – primary issue
   for section styling
 * [#57908](https://github.com/WordPress/gutenberg/pull/57908) – primary PR implementing
   section styles
 * [#61810](https://github.com/WordPress/gutenberg/discussions/61810) – discussion
   on CSSCSS Cascading Style Sheets. Specificity strategy that allows nesting of
   section styles
 * [#62686](https://github.com/WordPress/gutenberg/issues/62686) – issue opening
   a conversation about a potential path forward for the Global Styles architecture
   and features
 * [Styling sections, nested elements, and more with Block Style Variations in WordPress 6.6](https://developer.wordpress.org/news/2024/06/21/styling-sections-nested-elements-and-more-with-block-style-variations-in-wordpress-6-6/)–
   Developer Blogblog (versus network, site) post covering Section Styles

_Props to [@bph](https://profiles.wordpress.org/bph/), [@oandregal](https://profiles.wordpress.org/oandregal/)
and [@juanmaguitar](https://profiles.wordpress.org/juanmaguitar/) for review_

[#6-6](https://make.wordpress.org/core/tag/6-6/), [#core-editor](https://make.wordpress.org/core/tag/core-editor/),#
dev-note, [#dev-notes](https://make.wordpress.org/core/tag/dev-notes/), [#dev-notes-6-6](https://make.wordpress.org/core/tag/dev-notes-6-6/),
[#gutenberg](https://make.wordpress.org/core/tag/gutenberg/)

### Share this:

 * [  Threads ](https://make.wordpress.org/core/2024/06/24/section-styles/?share=threads)
 * [  Mastodon ](https://make.wordpress.org/core/2024/06/24/section-styles/?share=mastodon)
 * [  Bluesky ](https://make.wordpress.org/core/2024/06/24/section-styles/?share=bluesky)
 * [  X ](https://make.wordpress.org/core/2024/06/24/section-styles/?share=x)
 * [  Facebook ](https://make.wordpress.org/core/2024/06/24/section-styles/?share=facebook)
 * [  LinkedIn ](https://make.wordpress.org/core/2024/06/24/section-styles/?share=linkedin)

 1.  ![](https://secure.gravatar.com/avatar/2fa6f8b339fb29d2fff57252140bc46e0ab9879e9dc6a420e809c120f2c032f1?
     s=32&d=mm&r=g)
 2.   [Tim Nicholson](https://profiles.wordpress.org/timnicholson/)  5:50 pm _on_ July
     30, 2024
 3.  This is a really great step forward for themes to be able to much more heavily
     use jsonJSON JSON, or JavaScript Object Notation, is a minimal, readable format
     for structuring data. It is used primarily to transmit data between a server and
     web application, as an alternative to XML. files for styles, but I’ve noticed 
     that section style variations don’t actually affect the controls in the BlockBlock
     Block is the abstract term used to describe units of markup that, composed together,
     form the content or layout of a webpage using the WordPress editor. The idea combines
     concepts of what in the past may have achieved with shortcodes, custom HTML, and
     embed discovery into a single consistent API and user experience. Editor itself.
     
     In the examples of above that set background and text colors, those don’t get 
     set in the block settings in the editor. In fact, the colors in the block settings
     override the ones set in the section style. These styles also don’t seem to be
     able to be previewed when hovering over them like other custom styles. So where
     colors are already set on the block, the section style can’t be previewed and 
     does nothing when applied. So it definitely isn’t a good user experience. For 
     now, I’m setting !important in the section styles which will at least then override
     the colors set in the block itself but that really isn’t a good way to handle 
     things.
 4.  ![](https://secure.gravatar.com/avatar/d2ba618c7350498961f2be2ede2c508222165db74c8fa040e48b18aec6fc19f0?
     s=32&d=mm&r=g)
 5.   [Aaron Robertshaw](https://profiles.wordpress.org/aaronrobertshaw/)  12:39 am
     _on_ July 31, 2024
 6.  Thanks for the great feedback!
 7.  > I’ve noticed that section style variations don’t actually affect the controls
     > in the BlockBlock Block is the abstract term used to describe units of markup
     > that, composed together, form the content or layout of a webpage using the WordPress
     > editor. The idea combines concepts of what in the past may have achieved with
     > shortcodes, custom HTML, and embed discovery into a single consistent API and
     > user experience. Editor itself
 8.  That is correct. This is the first iteration of the feature and there are many
     more improvements in store for it.
 9.  Two primary factors led to the decision not to, for now, update the design tool
     values in the block inspector when a block style is applied.
 10. **Traditional Block Styles**
 11. Traditional block styles that style blocks via an enqueued stylesheet or inline
     styles don’t have data that can be easily parsed to update these controls. This
     would mean applying some styles would change values, and others would do nothing.
 12. This iteration of section styles leans more towards consistency until some of 
     the rough edges can be worked through. Improving the overall UXUX User experience
     was flagged as a “next step” so stay tuned over the next couple of releases.
 13. **Global Styles**
 14. Global Styles values aren’t reflected in the block inspector’s design tools either.
     The data for block style variations is merged into the overall Global Styles data
     set, so these two are tied together.
 15. The good news is work is already underway towards achieving a means of displaying
     style inheritance and where values are coming from. The following list of issues
     are great options to follow the progress as it unfolds.
 16.  * [Styles: Show a hierarchy of styles clearly](https://github.com/WordPress/gutenberg/issues/49278)
      * [Design Tools: Better handling of unset/inherited values](https://github.com/WordPress/gutenberg/issues/43082)
      * [Local block appearance controls should reflect values from Global Styles/Theme.json](https://github.com/WordPress/gutenberg/issues/37752)
 17. Also, it was only with this release that the post editor gained access to all 
     the merged Global Styles data which was a blockerblocker A bug which is so severe
     that it blocks a release. to achieving the UX you proposed. Now it is in place,
     there is a lot that can be done with it.
 18. > In fact, the colors in the block settings override the ones set in the section
     > styles
 19. This is the intended behaviour.
 20. Any styles assigned to a specific block instance should override anything set 
     at a more global level e.g. section styles, global block type styles, or generic
     global styles.
 21. > These styles also don’t seem to be able to be previewed when hovering over them
     > like other custom stylesheet
 22. The block style being hovered does get applied to the example block within the
     preview.
 23. Not all block previews are great examples though so some explorations have started
     around improving this. Ultimately, the goal might be to provide a scaled view 
     of the selected block so the preview is much more relevant.
 24. > For now, I’m setting !important in the section styles which will at least then
     > override the colors set in the block itself but that really isn’t a good way
     > to handle things.
 25. As noted above, styles set on individual blocks should be able to override section
     styles. I don’t recommend using `!important` in this manner.
 26. Take a scenario where a “dark” style was defined and used throughout the site.
     Its styles are great in almost all applications except there is one instance where
     perhaps you’d like to tweak the background color or enlarge the font. This is 
     where selecting the block instance and applying a customization is still useful
     and expected functionality.
 27. It sounds as though these section styles are being retroactively applied to existing
     blocks that already have existing styles on them.
 28. As more feedback is collected, if it makes sense to reset block instance styles
     when first applying a block style, that could be an option.
 29. The catch would still be the traditional block styles that enqueue stylesheets
     and inline styles. Maybe, in those cases, a clean reset is still desirable. Its
     something that can be explored when that bridged is crossed.
 30. I hope that helps clarify a few things. Thanks again for taking the time to leave
     a comment, it’s appreciated!
 31.  * ![](https://secure.gravatar.com/avatar/aedf0c39d8802b7643fb2b776e55039889cf7351f84eec087154c8521da222ee?
        s=32&d=mm&r=g)
      *  [Lauren](https://profiles.wordpress.org/oncecoupled/)  2:50 pm _on_ July 31,
        2024
      * Really appreciate this conversation and context, thank you!
 32. ![](https://secure.gravatar.com/avatar/d3ed10b2c9b140851235c075bc881392fc78ca95c2e23259391b0d3f171221da?
     s=32&d=mm&r=g)
 33.  [nickkadutskyi](https://profiles.wordpress.org/nickkadutskyi/)  4:28 pm _on_ 
     August 16, 2024
 34. Hi [@aaronrobertshaw](https://profiles.wordpress.org/aaronrobertshaw/) this looks
     great!
 35. Is it possible to have more than 1 levels of nested blocks?
      I am trying to do
     something like this (both in php and jsonJSON JSON, or JavaScript Object Notation,
     is a minimal, readable format for structuring data. It is used primarily to transmit
     data between a server and web application, as an alternative to XML.):
 36.     ```notranslate
         {
           "$schema": "https://schemas.wp.org/trunk/theme.json",
           "version": 3,
           "title": "Test",
           "slug": "test",
           "blockTypes": [
             "core/group"
           ],
           "styles": {
             "dimensions": {
               "minHeight": "50px"
             },
             "border": {
               "width": "1px",
               "style": "solid",
               "color": "red"
             },
             "blocks": {
               "core/group": {
                 "spacing": {
                   "padding": {
                     "top": "10px",
                     "bottom": "10px"
                   }
                 },
                 "border": {
                   "width": "1px",
                   "style": "solid",
                   "color": "orange"
                 },
                 "blocks": {
                   "core/group": {
                     "spacing": {
                       "padding": {
                         "top": "10px",
                         "bottom": "10px"
                       }
                     },
                     "border": {
                       "width": "1px",
                       "style": "solid",
                       "color": "yellow"
                     }
                   }
                 }
               }
             }
           }
         }
         ```
     
 37. I see that I can go one level deep with nested blockBlock Block is the abstract
     term used to describe units of markup that, composed together, form the content
     or layout of a webpage using the WordPress editor. The idea combines concepts 
     of what in the past may have achieved with shortcodes, custom HTML, and embed 
     discovery into a single consistent API and user experience. styles but not 2 or
     more.
      Am I doing it wrong or it’s not supported at the moment in WP 6.6.1?
 38.  * ![](https://secure.gravatar.com/avatar/d3ed10b2c9b140851235c075bc881392fc78ca95c2e23259391b0d3f171221da?
        s=32&d=mm&r=g)
      *  [nickkadutskyi](https://profiles.wordpress.org/nickkadutskyi/)  8:09 pm _on_
        August 16, 2024
      * I checked the [code here](https://github.com/WordPress/wordpress-develop/blob/4d8ac8b13cb2b233ce723789a920ec26c750458d/src/wp-includes/class-wp-theme-json.php#L992)
        and it seems like it’s not supported since the schema doesn’t include blocks
        field in nested blocks style definitions.
      * ![](https://secure.gravatar.com/avatar/d2ba618c7350498961f2be2ede2c508222165db74c8fa040e48b18aec6fc19f0?
        s=32&d=mm&r=g)
      *  [Aaron Robertshaw](https://profiles.wordpress.org/aaronrobertshaw/)  7:43 
        am _on_ August 19, 2024
      * Thanks for the question [@nickkadutskyi](https://profiles.wordpress.org/nickkadutskyi/)!
      * You are correct, nesting of blockBlock Block is the abstract term used to describe
        units of markup that, composed together, form the content or layout of a webpage
        using the WordPress editor. The idea combines concepts of what in the past 
        may have achieved with shortcodes, custom HTML, and embed discovery into a 
        single consistent API and user experience. type style definitions is not currently
        supported. This is also the case for general block type style definitions e.
        g. `styles.blocks.core/group`.
      * The code comment linked does break down what is supported in more detail but
        could also be clearer about this limitation:
      * >  - Block styles can contain `elements` & `variations` definitions.
        >  - Variations definitions cannot be nested.
        >  - Variations can contain styles for inner `blocks`.
        >  - Variation inner `blocks` styles **can contain `elements`**.
      * With Global Styles mostly being capped at `0-1-0` specificity, it does provide
        an opportunity for future iterations of this feature to support further nesting
        of block type styles.
      * I don’t know at this stage whether the benefits of this support outweigh the
        much greater complexity in code and within the UIUI User interface to customize
        such complex data structures.
      * My recommendation would be to compose style variations in a less monolithic
        fashion. Breaking them down to a level where only one level of inner block 
        definitions is needed, should make the block style variation easier to maintain,
        reuse more broadly, and apply predictably.
      * I hope that helps!
         - ![](https://secure.gravatar.com/avatar/d3ed10b2c9b140851235c075bc881392fc78ca95c2e23259391b0d3f171221da?
           s=32&d=mm&r=g)
         -  [Nick Kadutskyi](https://profiles.wordpress.org/nickkadutskyi/)  3:54 pm
           _on_ August 19, 2024
         - Thank you for clarification [@aaronrobertshaw](https://profiles.wordpress.org/aaronrobertshaw/)!
         - I am coding a BlockBlock Block is the abstract term used to describe units
           of markup that, composed together, form the content or layout of a webpage
           using the WordPress editor. The idea combines concepts of what in the past
           may have achieved with shortcodes, custom HTML, and embed discovery into
           a single consistent API and user experience. Pattern that is styled by a
           Block Style.
            Eventually I went for a flatter Block Pattern.
 39. ![](https://secure.gravatar.com/avatar/1ac80e2d5ca9079d8cf1cc29f968e56e1ac98ed1fdad537139c5267bcbedfab0?
     s=32&d=mm&r=g)
 40.  [Huan](https://profiles.wordpress.org/daodaotw/)  10:28 am _on_ September 5, 
     2024
 41. There are reports saying `blockGap` not working, and I can confirm it’s not working
     at the moment.
 42.  * ![](https://secure.gravatar.com/avatar/d2ba618c7350498961f2be2ede2c508222165db74c8fa040e48b18aec6fc19f0?
        s=32&d=mm&r=g)
      *  [Aaron Robertshaw](https://profiles.wordpress.org/aaronrobertshaw/)  7:10 
        am _on_ September 10, 2024
      * Thanks [@daodaotw](https://profiles.wordpress.org/daodaotw/), there’s an [existing issue](https://github.com/WordPress/gutenberg/issues/63273)
        for supporting blockBlock Block is the abstract term used to describe units
        of markup that, composed together, form the content or layout of a webpage 
        using the WordPress editor. The idea combines concepts of what in the past 
        may have achieved with shortcodes, custom HTML, and embed discovery into a 
        single consistent API and user experience. gap within section styles. Progress
        can be followed over on that issue.

Comments are closed.

# Post navigation

[← WordPress 6.6 CSS Specificity](https://make.wordpress.org/core/2024/06/21/wordpress-6-6-css-specificity/)

[Internationalization improvements in 6.6 →](https://make.wordpress.org/core/2024/06/24/i18n-improvements-6-6-2/)