Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 38 ยท Shadow DOM and Styling

Shared and Adopted Stylesheets

Share CSS between web components with constructable stylesheets and adoptedStyleSheets, reuse css tag fragments in Lit, build a design-token module and handle global styles safely.

Scoped styles are wonderful, but every component needs some of the same basics: a reset, a typography scale, button styles, focus rings. Copying the same CSS into fifty static styles blocks would be wasteful and impossible to maintain. This lesson shows how to share styles properly, first with the browser feature that makes it cheap (constructable stylesheets), then with the patterns Lit gives you on top.

You will also see why a global <link rel="stylesheet"> in the page does not reach components, and what to do instead.

Constructable stylesheets

In the past, a component that wanted CSS had to add a <style> element to its shadow root. With 500 instances, the browser parsed the same CSS 500 times. Modern browsers let you create one CSSStyleSheet object in JavaScript and adopt it into any number of shadow roots, so it is parsed once and shared.

adoptedStyleSheets by hand

After 1.5 seconds, a single insertRule call restyles all three tags at once. That is the power of sharing one live sheet. Lit's static styles uses exactly this mechanism under the hood: each css result is a lazily created CSSStyleSheet that Lit adopts into every instance's root. In browsers without support it falls back to <style> elements.

Reusing css fragments in Lit

In Lit, you share styles by exporting css results from a module and composing them in static styles:

JavaScript
// shared-styles.js
import { css } from "lit";

export const resetStyles = css`
  *, *::before, *::after { box-sizing: border-box; }
  :host { font-family: system-ui, sans-serif; }
`;

export const buttonStyles = css`
  button { padding: 8px 16px; border-radius: 8px; border: 0; background: var(--btn-bg, #2d5bd8); color: white; }
`;
JavaScript
// my-form.js
import { resetStyles, buttonStyles } from "./shared-styles.js";

class MyForm extends LitElement {
  static styles = [resetStyles, buttonStyles, css`:host { display: block; }`];
}

The important property: every component that includes buttonStyles shares the same CSSStyleSheet, so the CSS is parsed once. Order matters: later entries win ties, so put the reset first and component-specific rules last.

One fragment, three components

The base look lives in one place. Each component adds only what is different, using custom properties as the bridge. This also keeps the styles consistent when the design changes: edit surface once.

Extending a class's styles

When a class extends another Lit class, it can reuse the parent's styles:

JavaScript
class DangerAlert extends UiAlert {
  static styles = [UiAlert.styles, css`:host { --accent: #c62828; }`];
}

Using super.styles inside the static field also works. Without including the parent styles, the subclass would lose them, because the static property is replaced, not merged.

A design-token module

Many teams keep their tokens (colors, spacing, type scale) in one module and load them on :root, then use var(--token) in components:

CSS
/* tokens.css, loaded by the page */
:root {
  --space-1: 4px; --space-2: 8px; --space-3: 16px;
  --color-brand: #2d5bd8; --color-text: #1f2430;
  --radius: 8px;
}
@media (prefers-color-scheme: dark) {
  :root { --color-text: #e8ecf5; }
}

Because custom properties inherit into every shadow root (see CSS Custom Properties and Parts), a single global tokens file themes all components. Selectors cannot cross the boundary, but tokens can. This is the recommended way to connect a global design system to web components.

Global CSS frameworks and shadow DOM

A common surprise: adding Bootstrap or a utility CSS file to the page does not style the inside of a Lit component. Page stylesheets match only the light DOM. You have three options:

  1. Do not use the framework inside components. Write component CSS with tokens instead. This is the cleanest option for reusable widgets.
  2. Adopt the framework's stylesheet into the shadow root. Fetch it, create a CSSStyleSheet, and add it with adoptedStyleSheets. Fine for a small, controlled file; costly for large frameworks because every rule is applied inside every root.
  3. Render in light DOM with createRenderRoot() { return this; } for the few components that must use global classes.
JavaScript
const frameworkSheet = new CSSStyleSheet();
frameworkSheet.replaceSync(await (await fetch("/utility.css")).text());

class UsesUtilities extends LitElement {
  connectedCallback() {
    super.connectedCallback();
    this.renderRoot.adoptedStyleSheets = [...this.renderRoot.adoptedStyleSheets, frameworkSheet];
  }
}

Here renderRoot.adoptedStyleSheets already holds Lit's own sheets, so the code appends rather than replaces. This snippet is read-only in the editor above because it needs a server to fetch from.

@import and CSS modules

Do not use @import inside a constructed stylesheet: replaceSync ignores it, and replace can fetch it but makes loading asynchronous. Bundlers solve the problem better: with Vite you can import styles from "./card.css?inline" and wrap it with unsafeCSS(styles), keeping real .css files with editor support. Native CSS module scripts (import sheet from "./a.css" with { type: "css" }) work in recent Chromium and Safari; check support before depending on them.

Common mistakes

  • Replacing adoptedStyleSheets with a new array and dropping Lit's own sheet. Spread the old array.
  • Expecting global styles (Bootstrap, Tailwind classes) to apply in a shadow root.
  • Duplicating the same CSS in many components instead of sharing one css fragment.
  • Forgetting that a subclass's static styles replaces the parent's unless you include super.styles.
  • Putting @import in replaceSync. It is ignored.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the main benefit of a constructable stylesheet?

    A CSSStyleSheet created in JS is parsed once and can be adopted by many roots, saving time and memory.
  2. 2. How do you share a base style between two Lit components?

    css results are reusable objects. Placing them in the static styles array of each component shares one stylesheet.
  3. 3. Why does Bootstrap loaded in the page not style a Lit component's inner buttons?

    Document stylesheets match only the light DOM. Shadow roots need their own styles or adopted sheets.
  4. 4. What passes from global CSS into every shadow root?

    Custom properties inherit through the boundary, which makes tokens the bridge between a design system and components.

Summary

  • new CSSStyleSheet() plus adoptedStyleSheets shares one parsed stylesheet across many roots; Lit's static styles does this for you.
  • Export css fragments and compose them in an array; later entries win ties.
  • Subclasses must include super.styles to keep the parent's CSS.
  • Connect a global design system through custom properties, not through selectors.
  • Global frameworks do not reach into shadow roots; adopt their sheet, avoid them in components, or use light DOM.

Next: Shadow DOM Events and Focus