A new 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., known as the “Style Engine”, has been shipped in WordPress 6.1 to provide a single, centralized agent responsible for generating and rendering consistent 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. supports styles on the client-side and server-side.

For the 6.1 release, the focus has been on consolidating how WordPress generates block supports (border, color, spacing, and typography) and layout styles in the editor and frontend.

Before 6.1, a multitude of instances existed where block supports CSSCSS Cascading Style Sheets. and class names were compiled and/or enqueued, both in JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com and PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 7.4 or higher, resulting in a great deal of duplication in both code and frontend output. 

It’s imperative to note that the primary and very specific goal of the Style Engine is to improve how the Block editor compiles and renders block CSS, not to provide a universal approach to generating CSS.

Key enhancements in 6.1

WordPress 6.1 introduces a common way to compile, optimize and sanitize block supports styles. Previously block support CSS and class names were generated on demand creating inconsistencies and duplicated code.

Moreover, and one of the biggest improvements, 6.1 brings a way to add styles across the application to a single stylesheet, and also combine repetitive layout-specific CSS rules.

This functionality reduces the number of inline HTMLHTML HyperText Markup Language. The semantic scripting language primarily used for outputting content in web browsers. style tags printed to the page: all block supports and layout styles will be rendered to the page as a single, combined stylesheet.

For example, before 6.1, when a page included multiple block layout styles, a CSS rule for each block would be printed in a separate HTML style tagtag A directory in Subversion. WordPress uses tags to store a single snapshot of a version (3.6, 3.6.1, etc.), the common convention of tags in version control systems. (Not to be confused with post tags.). The amount of unique style tags for a single page were potentially without limit.

<style>.wp-block-columns.wp-container-1 { flex-wrap: nowrap; }</style>
<style>.wp-block-columns.wp-container-2 { flex-wrap: nowrap; }</style>
<style>.wp-block-columns.wp-container-3 { flex-wrap: nowrap; }</style>

As of 6.1, layout CSS rules with matching CSS definitions are combined in a single HTML style tag:

<style>.wp-block-columns.wp-container-1, .wp-block-columns.wp-container-2, .wp-block-columns.wp-container-3 { flex-wrap: nowrap; }</style>

Public Functions (API)

The following is a general overview of the public functions introduced in 6.1.

Please refer to the API documentation: @wordpress/style-engine for detailed information and example usage.

wp_style_engine_get_styles()

A global public function to generate block styles – CSS and class names – from a style object, e.g. the value of a block’s `attributes.style` object or the top-level styles in 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.. Through it, one can store CSS for later retrieval and eventual enqueuing on the frontend.

wp_style_engine_get_stylesheet_from_css_rules()

This function compiles and returns a stylesheet for a set of any CSS rules. Through it, one can store CSS for later retrieval and eventual enqueuing on the frontend.

wp_style_engine_get_stylesheet_from_context()

Returns compiled CSS stylesheet from stored styles, if any have been stored. The style engine will automatically merge declarations and combine selectors. 

JavaScript public functions

The JavaScript API is limited to use within the editor, and compiles only block support styles for now. It ensures that the styles in the editor match those you see on the frontend site. 

compileCSS()

Compiles and returns a CSS stylesheet for a given style object and selector. 

getCSSRules()

Given a style object, it returns a collection of objects containing the selector, if any, the CSS property key (camel case) and the parsed CSS value.

Example usage

WordPress 6.1 primarily uses the public methods cited above to create and enqueue block supports styles from a “style” object usually available as a property on the block attributes. 

An individual block’s style object may look like this:

$block_styles = array(
     'spacing'    => array(
        'padding' => '10px',
        'margin'  => array(
            'top' => '1em'
            ),
        ),
     'typography' => array(
        'fontSize' => '2.2rem'
    ),
);

wp_style_engine_get_styles() parses and sanitizes the incoming values, then compiles and returns CSS (a compiled string and an array of declarations), which can be used immediately or, if a context is specified in the options, stored for later retrieval.

$styles = wp_style_engine_get_styles(
    $block_styles,
    'options' => array( 'context' => 'block-supports' ),
);

/* 
    $styles is equal to:
    array(
       'css'          => 'padding:10px;margin-top:1em;font-size:2.2rem',
       'declarations' => array( 'padding' => '10px', 'margin-top' => '1em', 'font-size' => '2.2rem' )
    )
*/

Multiple instances of such styles may be “stored” across the application, before the page is rendered, and then retrieved and printed together as a single stylesheet when the page is rendered.

Note: The ‘context’ value is used to group and identify styles, so all styles that belong in the same stylesheet should be stored using the same context value.

The editor could then retrieve the stylesheet for all styles stored under the context value of ‘block-supports’ and enqueue them to be printed to the page in a single style tag:

function enqueue_my_block_supports_styles() {
    $block_supports_stylesheet = wp_style_engine_get_stylesheet_from_context( 'block-supports' );

    if ( ! empty( $block_supports_stylesheet ) ) {
       wp_register_style( 'my-block-supports-stylesheet', false, array(), true, true );
       wp_add_inline_style( 'my-block-supports-stylesheet', $stylesheet );
       wp_enqueue_style( 'my-block-supports-stylesheet' );
    }
}

add_action( 'wp_enqueue_scripts', 'enqueue_my_block_supports_styles' );

Using wp_style_engine_get_stylesheet_from_css_rules() is similar only that, instead of a block styles object, the first argument is a collection of CSS rules from which you can create a stylesheet.

$my_styles = array(
   array(
       'selector'     => '.orange',
       'declarations' => array( 'color' => 'orange' )
   ),
   array(
       'selector'     => '.red',
       'declarations' => array( 'color' => 'red' )
   ),
);

$my_stylesheet = wp_style_engine_get_stylesheet_from_css_rules(
   $my_styles,
   array(
       'context' => 'my-styles',
   )
);

Please refer to the API documentation: @wordpress/style-engine for detailed information and example usage.

Backwards compatibility and best practices

The Style Engine is a new API and, while it replaces the way block supports to generate CSS and class names, it does not modify the functionality of any existing global methods.

While backwards compatibility is a priority, the Style Engine is in its first iteration and therefore the underlying mechanics will be subject to some degree of transformation in the GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ 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/ or can be cost-based plugin from a third-party. and, ultimately, future versions of WordPress. 

To ensure ongoing compatibility, it is recommended to only use the above-mentioned public functions, and avoid calling public methods of any Style Engine utility class.

Current limitations and future enhancements

The Style Engine’s sole function in 6.1 is to generate coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. block supports CSS for the following styles:

• border
• color
• spacing
• typography

In future iterations, this list may be extensibleExtensible This is the ability to add additional functionality to the code. Plugins extend the WordPress core software..

The next milestones for the Style Engine are:

• to assume the responsibility of processing and rendering optimized frontend CSS for Global styles
• providing a way to generate all theme-related styles in one place, and
• further reducing the footprint of rendered styles

Ongoing development is taking place in WordPress/gutenberg: see the tracking issue and project board.

You can find more context on the history and planned features of the Style Engine on Block editor styles: initiatives and goals.

Further reading

• Block editor styles: initiatives and goals 
• GitHubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged by the repository owner. https://github.com/ tracking issue #38167
• GitHub project board.
• API documentation: @wordpress/style-engine

Props: @webcommsat and @bph for review

#6-1, #core-editor, #dev-notes, #dev-notes-6-1, #editor, #gutenberg