Introducing the Block Selectors API

The new 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. Selectors APIAPI 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 CSSCSS 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.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., 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