Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 38 ยท Shadow DOM and Styling

CSS Custom Properties and Parts

Make shadow DOM components themeable: expose CSS custom properties with defaults, share design tokens, open specific elements with part and exportparts, and choose between them.

Encapsulation is great until you want to change something. A designer asks for a red version of your button, or a dark theme for your card. Shadow DOM blocks outside selectors, so how does the page restyle a component? The standard gives you two deliberate openings: CSS custom properties, which pass through the boundary, and parts, which expose chosen elements to outside selectors.

You decide what the public styling API of your component is, the same way you decide its public methods. Anything not exposed stays private, so you can change the internal markup later without breaking users.

Custom properties: theme values flow in

CSS custom properties (also called CSS variables) are inherited, and inheritance passes through shadow roots. A component reads var(--name, fallback), and the page sets --name on the host or any ancestor.

A themeable badge

The same component looks different in four places without any change to its code. The fallback value after the comma (#eee) means the component works with no theme at all.

Designing a custom property API

Treat these names as public API and document them:

  • Prefix with the component name: --badge-bg, not --bg. This avoids clashes with the page's own variables.
  • Always give a fallback: var(--badge-bg, #eee).
  • Prefer semantic over structural names: --badge-bg rather than --badge-inner-span-background.
  • Allow a design-system layer: a component can default to a global token, for example var(--badge-bg, var(--color-surface, #eee)). Pages that define --color-surface re-theme everything at once.

Dark mode is a natural fit: set tokens on :root and switch them inside @media (prefers-color-scheme: dark). Every component updates, since they all read the tokens.

Parts: expose an element

Sometimes a value is not enough. A page may want to restyle the shape of an internal element, with borders, shadows and spacing. A part is a named element in the shadow tree that outside CSS can target with the ::part() pseudo-element.

Inside the component, add a part attribute. Outside, use ::part(name) on the host.

Styling a part from the page

The header and footer colors come from the page, and the hover rule also works because ::part() accepts a state pseudo-class such as :hover or :focus. The component stays in charge of structure: the page can never reach elements without a part attribute.

Rules of ::part()

  • It selects a part of a specific host: fancy-dialog::part(header).
  • It cannot be chained into the shadow tree: fancy-dialog::part(header) span is invalid, and so is ::part(a)::part(b). It can be followed by pseudo-classes and pseudo-elements: ::part(close):hover, ::part(label)::first-line.
  • An element may have several parts separated by spaces: part="button primary".
  • Part styles from the page beat the component's own rules for the same property, unless the component uses !important. This is deliberate: the page owner has the final say.

Parts through nested components: exportparts

When component A contains component B inside its shadow tree, B's parts are not visible to the page. Component A can forward them with exportparts:

HTML
<!-- inside A's shadow tree -->
<b-button exportparts="label, icon: button-icon"></b-button>

The page can then write a-component::part(label) and a-component::part(button-icon). The syntax is inner-name or inner-name: outer-name. The wrapper decides which parts to forward and under which names.

flowchart LR
  Page["Page CSS<br/>a-component::part(button-icon)"] --> A["a-component<br/>exportparts"]
  A --> B["b-button shadow tree<br/>part=icon"]

exportparts forwards a part from a nested component to the page.

Choosing between them

Need Use
Change a color, size, font or spacing value Custom property
Theme many components at once Shared custom properties (design tokens)
Restyle an element's borders, shadows, layout Part
Let a page add a hover or focus style on an inner element Part with a pseudo-class
Change structure or content Slots (see Slots and Component Composition in Lit)

A good component offers custom properties for the 80% case and a handful of parts for the rest. Too many parts make the internal structure part of your API, and every refactor is then a breaking change.

Light DOM as an escape hatch

If a component truly has to be styled by global CSS (for example, utility classes from Tailwind), you can render without a shadow root by overriding createRenderRoot() { return this; }. You lose encapsulation and slots. Many teams reserve this for page-level layout components and keep reusable widgets in shadow DOM.

Common mistakes

  • Unprefixed variable names, which clash with the page's tokens.
  • No fallback in var(), so the component breaks when nobody defines the variable.
  • Forgetting that custom properties inherit: setting --badge-bg on a parent affects all badges below it, including nested ones.
  • Writing ::part(header) p and expecting it to work. Add a part on the inner element, or expose a custom property.
  • Adding part everywhere "just in case". Each part becomes a promise you must keep.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why can a page theme a component with custom properties even though shadow DOM blocks selectors?

    Selectors are scoped, but inherited values, including custom properties, flow from the page into the shadow tree.
  2. 2. How does the page style an element marked part="header" inside <my-card>?

    ::part(name) selects exposed elements from outside the shadow tree.
  3. 3. What does exportparts do?

    A wrapper component lists the inner parts to expose with exportparts, optionally under new names.
  4. 4. Which is the better name for a public custom property of a badge component?

    A component prefix avoids clashes with the page's own variables and states what the property controls.

Summary

  • Custom properties pass through the shadow boundary; read them with var(--name, fallback) and document them.
  • part="name" exposes an element; the page styles it with host::part(name), including pseudo-classes.
  • exportparts forwards parts of nested components.
  • Choose custom properties for values, parts for shape, slots for content.
  • Every property and part you expose is public API, so keep the list short and well named.

Next: Shared and Adopted Stylesheets