Didn't make the #ChromeDevSummit this year? Catch all the content (and more!) in the Chrome Dev Summit 2019 playlist on our Chrome Developers YouTube Channel.

Constructable Stylesheets: seamless reusable styles

Constructable Stylesheets are a new way to create and distribute reusable styles when using Shadow DOM.

It has always been possible to create stylesheets using JavaScript. However, the process has historically been to create a <style> element using document.createElement('style'), and then access its sheet property to obtain a reference to the underlying CSSStyleSheet instance. This method can produce duplicate CSS code and its attendant bloat, and the act of attaching leads to a flash of unstyled content whether there is bloat or not. The CSSStyleSheet interface is the root of a collection of CSS representation interfaces referred to as the CSSOM, offering a programmatic way to manipulate stylesheets as well as eliminating the problems associated with the old method.

Diagram showing preparation and application of CSS

Constructable Stylesheets make it possible to define and prepare shared CSS styles, and then apply those styles to multiple Shadow Roots or the Document easily and without duplication. Updates to a shared CSSStyleSheet are applied to all roots into which it has been adopted, and adopting a stylesheet is fast and synchronous once the sheet has been loaded.

The association set up by Constructable Stylesheets lends itself well to a number of different applications. It can be used to provide a centralized theme used by many components: the theme can be a CSSStyleSheet instance passed to components, with updates to the theme propagating out to components automatically. It can be used to distribute CSS Custom Property values to specific DOM subtrees without relying on the cascade. It can even be used as a direct interface to the browser’s CSS parser, making it easy to preload stylesheets without injecting them into the DOM.

Constructing a StyleSheet

Rather than introducing a new API to accomplish this, the Constructable StyleSheets specification makes it possible to create stylesheets imperatively by invoking the CSSStyleSheet() constructor. The resulting CSSStyleSheet object has two new methods that make it safer to add and update stylesheet rules without triggering Flash of Unstyled Content (FOUC). replace() returns a Promise that resolves once any external references (@imports) are loaded, whereas replaceSync() doesn’t allow external references at all:

const sheet = new CSSStyleSheet();

// replace all styles synchronously:
sheet.replaceSync('a { color: red; }');

// this throws an exception:
try {
  sheet.replaceSync('@import url("styles.css")');
} catch (err) {
  console.error(err); // imports are not allowed
}

// replace all styles, allowing external resources:
sheet.replace('@import url("styles.css")')
  .then(sheet => {
    console.log('Styles loaded successfully');
  })
  .catch(err => {
    console.error('Failed to load:', err);
  });

Using Constructed StyleSheets

The second new feature introduced by Constructable StyleSheets is an adoptedStyleSheets property available on Shadow Roots and Documents. This lets us explicitly apply the styles defined by a CSSStyleSheet to a given DOM subtree. To do so, we set the property to an array of one or more stylesheets to apply to that element.

// Create our shared stylesheet:
const sheet = new CSSStyleSheet();
sheet.replaceSync('a { color: red; }');

// Apply the stylesheet to a document:
document.adoptedStyleSheets = [sheet];

// Apply the stylesheet to a Shadow Root:
const node = document.createElement('div');
const shadow = node.attachShadow({ mode: 'open' });
shadow.adoptedStyleSheets = [sheet];

Notice that we’re overriding the value of adoptedStyleSheets instead of changing the array in place. This is required because the array is frozen; in-place mutations like push() throw an exception, so we have to assign a new array. To preserve any existing StyleSheets added via adoptedStyleSheets, we can use concat to create a new array that includes the existing sheets as well as additional ones to add:

const sheet = new CSSStyleSheet();
sheet.replaceSync('a { color: red; }');

// Combine existing sheets with our new one:
document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];

Putting it All Together

With Constructable StyleSheets, web developers now have an explicit solution for creating CSS StyleSheets and applying them to DOM trees. We have a new Promise-based API for loading StyleSheets from a string of CSS source that uses the browser’s built-in parser and loading semantics. Finally, we have a mechanism for applying stylesheet updates to all usages of a StyleSheet, simplifying things like theme changes and color preferences.

View Demo

Looking Ahead

The initial version of Constructable Stylesheets is shipping with the API described here, but there’s work underway to make things easier to use. There’s a proposal to extend the adoptedStyleSheets FrozenArray with dedicated methods for inserting and removing stylesheets, which would obviate the need for array cloning and avoid potential duplicate stylesheet references.

More Information

Was this page helpful?
Yes
What was the best thing about this page?
It helped me complete my goal(s)
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
It had the information I needed
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
It had accurate information
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
It was easy to read
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
Something else
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
No
What was the worst thing about this page?
It didn't help me complete my goal(s)
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
It was missing information I needed
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
It had inaccurate information
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
It was hard to read
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.
Something else
Thank you for the feedback. If you have specific ideas on how to improve this page, please create an issue.

rss_feed Subscribe to our RSS or Atom feed and get the latest updates in your favorite feed reader!