Skip to content
Tutorials Center
My learning

Topics

Lesson 30 of 39 ยท Styling and Theming

CSS Custom Properties for Theming Components

Use CSS custom properties as the main theming API for shadow DOM components, with defaults, fallbacks, design tokens, dark mode and a documented list of variables.

Shadow DOM walls your styles off from the page. That is the point, but it raises a question: how does a page author change the color of your button? Overriding internal class names is impossible. The first and most important answer is CSS custom properties (CSS variables). They are inherited, so they pass straight through shadow boundaries, which makes them the natural public styling API of a component.

Variables cross the boundary

Normal selectors cannot reach into a shadow root, but inheritance still works. A custom property set on the page, on an ancestor, or on the host is visible to every element inside the shadow tree.

Variables passing into shadow DOM

Each use picks up its nearest definition. The first has none, so the fallback values after the commas apply. That var(--name, fallback) form is the heart of the pattern: the component always looks good by default and can be customized without any change to its code.

Designing the variable API

Treat custom properties like function parameters: name them clearly, document them, and keep the set small.

  • Prefix with the component name: --badge-bg, --tabs-gap. This avoids clashes with page variables.
  • Name by purpose, not by implementation: --card-accent beats --card-border-left-color.
  • Always provide a fallback in var(), or define defaults on :host.
  • Document each variable, its type and its default, the way you would for attributes.

Defining defaults on :host has one catch: a value set on :host inside the shadow root has lower priority than a value set by the page on the element itself (outer styles win over :host rules), so page authors can still override. But it also blocks inheritance from ancestors, since :host sets the property on the host itself. Using the var() fallback keeps inheritance working, which is usually what you want.

Layered tokens

Large systems use two layers: global design tokens (brand colors, spacing scale) and component tokens that default to the globals.

CSS
/* page / theme */
:root {
  --color-primary: #2563eb;
  --space-2: 0.5rem;
}

/* inside the component */
button {
  background: var(--button-bg, var(--color-primary, #2563eb));
  padding: var(--button-padding, var(--space-2, 0.5rem));
}

A page can restyle every component at once by changing --color-primary, or one component type by setting --button-bg. The nested fallbacks make each layer optional.

Dark mode

Because variables inherit, dark mode is a few lines of CSS on the page. Components need no knowledge of it.

One toggle themes every component

You can also react to the user's system setting with @media (prefers-color-scheme: dark) in the page CSS, or use the light-dark() function with color-scheme. All of these simply change the variables the components already read.

Typed values and @property

Plain custom properties are untyped strings. The @property at-rule registers one with a syntax, an initial value and an inheritance flag. It must live in the document stylesheet (registrations in a shadow root are not supported), which suits global tokens:

CSS
@property --accent {
  syntax: "<color>";
  inherits: true;
  initial-value: #2563eb;
}

Registration gives validation (an invalid value falls back to the initial one) and makes the property animatable, for example a color transition driven only by changing --accent.

What variables cannot do

A custom property can only set a value. It cannot add a new rule, change layout structure or style internals you did not expose. When pages need more control than a handful of variables give, use shadow parts, the topic of the next lesson. A good component uses both: variables for the common knobs, parts for the rest.

Common mistakes

  • Forgetting fallbacks, so a missing variable produces an invalid, invisible style.
  • Setting defaults on :host and wondering why inherited values from ancestors stop working.
  • Exposing dozens of variables; each one is a promise you must maintain.
  • Using generic names like --color that collide with the page.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why do custom properties work for theming across shadow boundaries?

    Custom properties inherit by default, so values set outside flow into the shadow tree.
  2. 2. What does var(--badge-bg, #e0e0e0) do when --badge-bg is not set?

    The second argument is the fallback used when the variable is not defined.
  3. 3. Why prefix variable names with the component name?

    A prefix like --badge- prevents clashes and tells authors which component the knob belongs to.
  4. 4. Where must an @property rule be placed?

    Registrations inside shadow roots are ignored, so register typed properties in the main document CSS.

Summary

  • Custom properties inherit through shadow roots, so they are the primary theming API.
  • Always provide var() fallbacks and prefix names with the component.
  • Layer component tokens over global design tokens for flexible theming and dark mode.
  • Use @property in the document for typed, animatable tokens; use parts when variables are not enough.

Next: Shadow Parts and exportparts