The new 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. Selectors API An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. allows more flexibility in how global styles are applied to blocks. As the available design tools grow in number and complexity, not all styles can be applied neatly to a block’s wrapping element.
In WordPress 5.8, the __experimentalSelector
property was introduced and later evolved to facilitate applying feature-level global styles, such as borders, colors, and typography, to arbitrary selectors. Similarly, the __experimentalDuotone
property was also introduced in WordPress 5.8 to support the application of SVG filters.
As advancements in design tools continue, the need for greater control over the application of global styles has grown more pressing. It is, for this reason, the selectors API has been extended and stabilized.
New selectors API features
Through the new API, a block can configure multiple CSS Cascading Style Sheets. selectors for use in generating global styles. These can be set at three different levels; root, feature, and sub-feature.
Root selectors
A root selector is the block’s primary CSS selector.
All blocks require a primary CSS selector for their global style declarations to be included under. If one hasn’t been supplied via the Block Selectors API, a default will be generated in the form of .wp-block-<name>
.
Example:
{
...
"selectors": {
"root": ".my-custom-block-selector"
}
}
Feature-level selectors
This level of selector relates to styles for specific block support, such as border, color, typography, etc. They allow for a block to apply such styles to different elements within a block. For example, applying colors to the block’s wrapper but typographic styles to an inner text element.
Example:
{
...
"selectors": {
"root": ".my-custom-block-selector",
"color": ".my-custom-block-selector",
"typography": ".my-custom-block-selector > h2"
}
}
Subfeature selectors
These selectors relate to individual styles provided by block support e.g. background-color
or border-radius
.
A subfeature can now have styles generated under its own unique selector. This is most useful when a single feature’s styles need to be applied to separate elements. For example, a block’s typography might require font-family
on the wrapper but text-decoration
and font-size
on different inner elements.
Example:
{
...
"selectors": {
"root": ".my-custom-block-selector",
"color": ".my-custom-block-selector",
"typography": {
"root": ".my-custom-block-selector > h2",
"text-decoration": ".my-custom-block-selector > h2 span"
}
}
}
Shorthand
For convenience, instead of specifying the same selector for every subfeature, you can define a simple string at the feature level.
Fallbacks
If a selector has not been configured for a given feature, it will fall back to the block’s root selector. Similarly, if a subfeature has no custom selector set, it will fall back first to its parent feature’s selector before the block’s root selector.
A detailed example configuration and explanation can be found in the Block Selectors API reference guide.
Backwards compatibility
Blocks currently using the __experimentalSelector
and __experimentalDuotone
support properties will continue to function as before.
However, if a block adds a selectors property in its block.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., that selectors configuration will be honored in its entirety. In other words, a block cannot use both the Selectors API and the old experimental properties.
Links
Props to @bph, @annezazu, @priethor and @leonnugraha for reviewing.
#6-3, #dev-notes, #dev-notes6-3