Runtime helpers for registering styles and injecting them into one or more documents.
CSS module imports are evaluated as JavaScript module side effects. By default,
that means generated style tags are inserted into the root document. This works
for most screens, but it does not cover styles for components rendered inside
another document, such as an iframe canvas.
@wordpress/style-runtime keeps a shared registry of style text and target
documents. Build tooling can register compiled styles when CSS modules are
imported, while host components can register additional documents that should
receive those styles.
Usage
Generated CSS module output registers styles with a stable hash:
import { registerStyle } from '@wordpress/style-runtime';
registerStyle( 'style-hash', '.example{color:red;}' );
Hosts that render package components into another document register that
document as a style target:
import { registerDocument } from '@wordpress/style-runtime';
const unregisterDocument = registerDocument( iframe.contentDocument );
// Later, when the document is no longer used:
unregisterDocument();
When a document is registered, all previously registered styles are injected
into it. Future styles are injected into every registered document.
The runtime coordinates separately bundled copies of this package through a
reserved globalThis.__wpStyleRuntime object. Consumers should use the public
APIs below instead of reading or writing that global directly.
API
registerStyle
Registers CSS text under a stable hash and injects it into all registered
documents. The hash is used to deduplicate style tags, so the same style is not
inserted more than once per document.
Registered styles are retained for the lifetime of the page so they can be
replayed into documents that are registered later.
import { registerStyle } from '@wordpress/style-runtime';
registerStyle( 'style-hash', '.example{color:red;}' );
registerDocument
Registers a document as a style injection target and returns a cleanup
function. Documents are reference-counted, so the same document can be
registered by multiple providers and will only stop receiving future styles
after every registration has been cleaned up.
import { registerDocument } from '@wordpress/style-runtime';
const cleanup = registerDocument( document );
cleanup();
Contributing to this package
This is an individual package that’s part of the Gutenberg project. The project is organized as a monorepo. It’s made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to npm and used by WordPress as well as other software projects.
To find out more about contributing to this package or Gutenberg as a whole, please read the project’s main contributor guide.