@wordpress/style-engine
Advanced tools
The Style Engine aims to provide a consistent API for rendering styling for blocks across both client-side and server-side applications.
Initially, it will offer a single, centralized agent responsible for generating block styles, and, in later phases, it will also assume the responsibility of processing and rendering optimized frontend CSS.
This package is new as of WordPress 6.1 and therefore in its infancy.
Upcoming tasks on the roadmap include, but are not limited to, the following:
attributes.fontSize.For more information about the roadmap, please refer to Block editor styles: initiatives and goals and the GitHub project board.
If you're making changes or additions to the Style Engine, please take a moment to read the notes on contributing.
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.
See also Using the Style Engine to generate block supports styles.
Parameters
array A block's attributes.style object or the top level styles in theme.jsonarray<string|boolean> An array of options to determine the output.
string An identifier describing the origin of the style object, e.g., 'block-supports' or 'global-styles'. Default is 'block-supports'. When both context and selector are set, the Style Engine will store the CSS rules using the context as a key.boolean Whether to skip converting CSS var:? values to var( --wp--preset--* ) values. Default is false.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:
wp_style_engine_get_styles will return the compiled CSS and CSS declarations array.
As mentioned, wp_style_engine_get_styles() is useful whenever you wish to generate CSS and/or classnames from a block's style object. A good example is using the Style Engine to generate block supports styles.
In the following snippet, we're taking the style object from a block's attributes and passing it to the Style Engine to get the styles. By passing a context in the options, the Style Engine will store the styles for later retrieval, for example, should you wish to batch enqueue a set of CSS rules.
$block_attributes = array(
'style' => array(
'spacing' => array( 'padding' => '100px' ),
),
);
$styles = wp_style_engine_get_styles(
$block_attributes['style'],
array(
'selector' => '.a-selector',
'context' => 'block-supports',
)
);
print_r( $styles );
/*
array(
'css' => '.a-selector{padding:100px}'
'declarations' => array( 'padding' => '100px' )
)
*/
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 register the styles in a store where a context string is passed in the options.
Parameters
array<array>array<string|bool> An array of options to determine the output.
string An identifier describing the origin of the style object, e.g., 'block-supports' or 'global-styles'. Default is 'block-supports'. When set, the Style Engine will attempt to store the CSS rules.bool Whether to add new lines and indents to output. Default is to inherit the value of the global constant SCRIPT_DEBUG, if it is defined.bool Whether to optimize the CSS output, e.g., combine rules. Default is false.Returns
string A compiled CSS string based on $css_rules.
Useful for when you wish to compile a bespoke set of CSS rules from a series of selector + declaration items.
The Style Engine will return a sanitized stylesheet. By passing a context identifier in the options, the Style Engine will store the styles for later retrieval, for example, should you wish to batch enqueue a set of CSS rules.
You can call wp_style_engine_get_stylesheet_from_css_rules() multiple times, and, so long as your styles use the same context identifier, they will be stored together.
$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' )
),
);
$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.
)
);
print_r( $stylesheet ); // .wp-pumpkin{color:orange}.wp-tomato{color:red;padding:100px}
It's also possible to build simple, nested CSS rules using the rules_group key.
$styles = array(
array(
'rules_group' => '@media (min-width: 80rem)',
'selector' => '.wp-carrot',
'declarations' => array( 'color' => 'orange' )
),
array(
'rules_group' => '@media (min-width: 80rem)',
'selector' => '.wp-tomato',
'declarations' => array( 'color' => 'red' )
),
);
$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.
)
);
print_r( $stylesheet ); // @media (min-width: 80rem){.wp-carrot{color:orange}}@media (min-width: 80rem){.wp-tomato{color:red;}}
Returns compiled CSS from a stored context, if found.
Parameters
string An identifier describing the origin of the style object, e.g., 'block-supports' or ' global-styles'. Default is 'block-supports'.array<bool> An array of options to determine the output.
bool Whether to add new lines and indents to output. Default is to inherit the value of the global constant SCRIPT_DEBUG, if it is defined.bool Whether to optimize the CSS output, e.g., combine rules. Default is false.Returns
string A compiled CSS string from the stored CSS rules.
Use this function to generate a stylesheet using all the styles stored under a specific context identifier.
A use case would be when you wish to enqueue all stored styles for rendering to the frontend. The Style Engine will merge and deduplicate styles upon retrieval.
// First, let's gather and register our styles.
$styles = array(
array(
'selector' => '.wp-apple',
'declarations' => array( 'color' => 'green' )
),
);
wp_style_engine_get_stylesheet_from_css_rules(
$styles,
array(
'context' => 'fruit-styles',
)
);
// Later, we fetch compiled rules from context store.
$stylesheet = wp_style_engine_get_stylesheet_from_context( 'fruit-styles' );
print_r( $stylesheet ); // .wp-apple{color:green;}
if ( ! empty( $stylesheet ) ) {
wp_register_style( 'my-stylesheet', false, array(), true, true );
wp_add_inline_style( 'my-stylesheet', $stylesheet );
wp_enqueue_style( 'my-stylesheet' );
}
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.
Generates a stylesheet for a given style object and selector.
Parameters
Style: Style object, for example, the value of a block's attributes.style object or the top level styles in theme.jsonStyleOptions: Options object with settings to adjust how the styles are generated.Returns
string: A generated stylesheet or inline style declarations.Changelog
6.1.0 Introduced in WordPress core.
Returns a JSON representation of the generated CSS rules.
Parameters
Style: Style object, for example, the value of a block's attributes.style object or the top level styles in theme.jsonStyleOptions: Options object with settings to adjust how the styles are generated.Returns
GeneratedCSSRule[]: A collection of objects containing the selector, if any, the CSS property key (camelcase) and parsed CSS value.Changelog
6.1.0 Introduced in WordPress core.
Returns a WordPress CSS custom var value from incoming style preset value, if one is detected.
The preset value is a string and follows the pattern var:description|context|slug.
Example:
getCSSValueFromRawStyle( 'var:preset|color|heavenlyBlue' ) // returns 'var(--wp--preset--color--heavenly-blue)'
Parameters
StyleValue: A string representing a raw CSS value. Non-strings won't be processed.Returns
StyleValue: A CSS custom var value if the incoming style value is a preset value.A guide to the terms and variable names referenced by the Style Engine package.
{ spacing: { margin: '10px' }, color: { ... }, ... }color: pink border, font-size, width...p.my-cool-classname > span. A CSS selector matches HTML elements based on the contents of the "class" attribute. See MDN CSS selectors article.10vw in height: 10vw.--wp--preset--olive: #808000;) and accessed using the var() function (e.g., color: var( --wp--preset--olive );). See MDN article on CSS custom properties.
FAQs
A suite of parsers and compilers for WordPress styles.
The npm package @wordpress/style-engine receives a total of 78,489 weekly downloads. As such, @wordpress/style-engine popularity was classified as popular.
We found that @wordpress/style-engine demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 23 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.