Style Engine

The Style Engine powering global styles and block customizations.

Backend API

wp_style_engine_get_styles()

Global public function to generate styles from a single style object, e.g., the value of a block's attributes.style object or the top level styles in theme.json .

Parameters

• $block_styles array A block's attributes.style object or the top level styles in theme.json
• $options array<string|boolean> An array of options to determine the output.
  • context string An identifier describing the origin of the style object, e.g., 'block-supports' or ' global-styles'. Default is 'block-supports'.
  • enqueue boolean When true will attempt to store and enqueue for rendering in a style tag on the site frontend.
  • convert_vars_to_classnames boolean Whether to skip converting CSS var:? values to var( --wp--preset--* ) values. Default is false.
  • selector string When a selector is passed, generate() will return a full CSS rule $selector { ...rules }, otherwise a concatenated string of properties and values.

Returns array<string|array>|null

array(
    'css'           => (string) A CSS ruleset or declarations block formatted to be placed in an HTML `style` attribute or tag.
    'declarations'  => (array) An array of property/value pairs representing parsed CSS declarations.
    'classnames'    => (string) Classnames separated by a space.
);

It will return compiled CSS declarations for inline styles, or, where a selector is provided, a complete CSS rule.

To enqueue a style for rendering in the site's frontend, the $options array requires the following:

1. selector (string) - this is the CSS selector for your block style CSS declarations.
2. context (string) - this tells the style engine where to store the styles. Styles in the same context will be batched together and printed in the same HTML style tag. The default is 'block-supports'.
3. enqueue (boolean) - tells the style engine to store the styles.

wp_style_engine_get_styles will return the compiled CSS and CSS declarations array.

Usage

$block_styles =  array(
     'spacing' => array( 'padding' => '100px' )
);
$styles = wp_style_engine_get_styles(
    $block_styles,
    array(
        'selector' => '.a-selector',
        'context'  => 'block-supports',
        'enqueue'  => true,
    )
);
print_r( $styles );

/*
array(
    'css'                 => '.a-selector{padding:10px}'
    'declarations'  => array( 'padding' => '100px' )
)
*/

wp_style_engine_get_stylesheet_from_css_rules()

Use this function to compile and return a stylesheet for any CSS rules. The style engine will automatically merge declarations and combine selectors.

This function acts as a CSS compiler, but will also enqueue styles for rendering where enqueue and context strings are passed in the options.

Parameters

• $css_rules array<array>
• $options array<string|boolean> An array of options to determine the output.
  • context string An identifier describing the origin of the style object, e.g., 'block-supports' or ' global-styles'. Default is 'block-supports'.
  • enqueue boolean When true will store using the context value as a key.

Returns string A compiled CSS string based on $css_rules.

Usage

$styles = array(
    array(
        'selector'.       => '.wp-pumpkin',
        'declarations' => array( 'color' => 'orange' )
    ),
    array(
        'selector'.       => '.wp-tomato',
        'declarations' => array( 'color' => 'red' )
    ),
    array(
        'selector'.       => '.wp-tomato',
        'declarations' => array( 'padding' => '100px' )
    ),
    array(
        'selector'.       => '.wp-kumquat',
        'declarations' => array( 'color' => 'orange' )
    ),
);

$stylesheet = wp_style_engine_get_stylesheet_from_css_rules(
    $styles,
    array(
        'context'  => 'block-supports', // Indicates that these styles should be stored with block supports CSS.
        'enqueue'  => true, // Render the styles for output.
    )
);
print_r( $stylesheet ); // .wp-pumpkin, .wp-kumquat {color:orange}.wp-tomato{color:red;padding:100px}

wp_style_engine_get_stylesheet_from_store()

Returns compiled CSS from a store, if found.

Parameters

• $store_key string An identifier describing the origin of the style object, e.g., 'block-supports' or ' global-styles'. Default is 'block-supports'.

Returns string A compiled CSS string from the stored CSS rules.

Usage

// First register some styles.
$styles = array(
    array(
        'selector'.       => '.wp-apple',
        'declarations' => array( 'color' => 'green' )
    ),
);

$stylesheet = wp_style_engine_get_stylesheet_from_css_rules(
    $styles,
    array(
        'context'  => 'fruit-styles',
        'enqueue'  => true,
    )
);

// Later, fetch compiled rules from store.
$stylesheet = gutenberg_style_engine_get_stylesheet_from_store( 'fruit-styles' );
print_r( $stylesheet ); // .wp-apple{color:green;}

Installation (JS only)

Install the module

npm install @wordpress/style-engine --save

This package assumes that your code will run in an ES2015+ environment. If you're using an environment that has limited or no support for such language features and APIs, you should include the polyfill shipped in @wordpress/babel-preset-default in your code.

Important

This Package is considered experimental at the moment. The idea is to have a package used to generate styles based on a style object that is consistent between: backend, frontend, block style object and theme.json.

Because this package is experimental and still in development it does not yet generate a wp.styleEngine global. To get there, the following tasks need to be completed:

TODO List:

• Add style definitions for all the currently supported styles in blocks and theme.json.
• The CSS variable shortcuts for values (for presets...)
• Support generating styles in the frontend. (Ongoing)
• Support generating styles in the backend (block supports and theme.json stylesheet). (Ongoing)
• Refactor all block styles to use the style engine server side. (Ongoing)
• Consolidate global and block style rendering and enqueuing
• Refactor all blocks to consistently use the "style" attribute for all customizations (get rid of the preset specific attributes).

See Tracking: Add a Style Engine to manage rendering block styles #38167

Glossary

A guide to the terms and variable names referenced by the Style Engine package.

Block style (Gutenberg internal)

An object comprising a block's style attribute that contains a block's style values. E.g., { spacing: { margin: '10px' }, color: { ... }, ... }

Global styles (Gutenberg internal)

A merged block styles object containing values from a theme's theme.json and user styles settings.

CSS declaration or (CSS property declaration)

A CSS property paired with a CSS value. E.g., color: pink

CSS declarations block

A set of CSS declarations usually paired with a CSS selector to create a CSS rule.

CSS property

Identifiers that describe stylistic, modifiable features of an HTML element. E.g., border, font-size, width...

CSS rule

A CSS selector followed by a CSS declarations block inside a set of curly braces. Usually found in a CSS stylesheet.

CSS selector

The first component of a CSS rule, a CSS selector is a pattern of elements, classnames or other terms that define the element to which the rule’s CSS definitions apply. E.g., p.my-cool-classname > span. See MDN CSS selectors article.

CSS stylesheet

A collection of CSS rules contained within a file or within an HTML style tag.

CSS value

The value of a CSS property. The value determines how the property is modified. E.g., the 10vw in height: 10vw.

CSS variables (vars) or CSS custom properties

Properties, whose values can be reused in other CSS declarations. Set using custom property notation (e.g., --wp--preset--olive: #808000;) and accessed using the var() function (e.g., color: var( --wp--preset--olive );). See MDN article on CSS custom properties.

Inline styles

Inline styles are CSS declarations that affect a single HTML element, contained within a style attribute

Usage

generate

Generates a stylesheet for a given style object and selector.

Parameters

• style Style: Style object.
• options StyleOptions: Options object with settings to adjust how the styles are generated.

Returns

• string: generated stylesheet.

getCSSRules

Returns a JSON representation of the generated CSS rules.

Parameters

• style Style: Style object.
• options StyleOptions: Options object with settings to adjust how the styles are generated.

Returns

• GeneratedCSSRule[]: generated styles.