In WordPress 6.6, Section Styles 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
- What’s Changed?
- Usage
- Registration of Block Style Variations
- Defining Block Style Variations
- Theme.json Partial Files
- Programmatically
- Via Theme Style Variations (Not Recommended)
- Backwards Compatibility
- Limitations
- What’s Next?
- Useful Links
What’s Changed?
Section-based styling has been enabled by extending the existing Block Styles feature (aka block 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 (0-1-0) for Global Styles introduced 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.json 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.
{
"$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 plugin 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/ 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.
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.
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 capabilities 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.
{
"$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:
- 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.
- Block style variations cannot redefine or customize inner block style variations.
- Block style variations do not support their own custom
settings values (yet).
- Custom block style variations cannot be applied and previewed within the Style Book.
What’s Next?
The Global Styles UI 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 enhancement 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
Props to @bph, @oandregal and @juanmaguitar for review
#6-6, #core-editor, #dev-note, #dev-notes, #dev-notes-6-6, #gutenberg
