Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 39 ยท Styling and Theming

Shadow Parts and exportparts

Expose chosen internal elements of a shadow tree for outside styling with the part attribute, the ::part() pseudo-element, exportparts and the theme attribute pattern.

CSS custom properties are great for colors and sizes, but sometimes a page needs to restyle a specific piece of your component: the button inside a dialog, the header of a card, the thumb of a slider. You cannot reach it with a normal selector, and exposing a variable for every possible property would be endless.

Shadow parts solve it. The component author marks selected internal elements with a part attribute, and the page styles them with the ::part() pseudo-element. The author chooses what is exposed, so the internals stay private by default.

Marking and styling a part

Inside the shadow DOM, add part="name" to an element. Outside, write host-selector::part(name) { ... }.

Styling a part from the page

The page controls the look of the header, body and button; the component controls everything else (borders, padding, layout). The internal class names .h and .b are not part of the API and can change freely.

Rules and limits of ::part()

  • ::part() selects a single level: x-card::part(header) works, but you cannot write x-card::part(header) span, and you cannot chain ::part(a)::part(b).
  • It can be combined with state pseudo-classes such as :hover, :focus, :active, and with a few pseudo-elements like ::before, ::after, ::placeholder. It cannot be combined with structural pseudo-classes such as :first-child.
  • An element may have several part names: part="header primary".
  • Part styles from the page win over the styles in the shadow tree (unless !important is used inside), so authors can override cleanly.

exportparts: parts across nested components

Imagine <x-dialog> whose shadow DOM contains an <x-button>. The button's own parts live in its shadow tree. The page can reach x-dialog::part(...) but not the button's internals, unless the dialog forwards them with exportparts.

HTML
<!-- inside x-dialog's shadow root -->
<x-button part="confirm" exportparts="label, icon: confirm-icon"></x-button>

The syntax is a comma-separated list: inner-name re-exports with the same name, inner-name: outer-name renames it. The page can now write:

CSS
x-dialog::part(confirm) { margin-left: auto; }
x-dialog::part(label)   { font-weight: 700; }
x-dialog::part(confirm-icon) { display: none; }
Forwarding parts with exportparts

The chip's label part is renamed chip-label on the panel, so the page styles it with x-panel::part(chip-label). Without exportparts that rule would match nothing.

Design guidance

Expose few, meaningful parts. Every part is a public promise: renaming or removing one breaks users. Choose stable names that describe a role (header, thumb, label), not an implementation detail (div2).

Parts vs variables. A rough guide:

Need Use
Colors, spacing, radius, fonts Custom properties
Anything else about one piece (borders, shadows, layout tweaks, hiding) Parts
Structure changes Slots, or a new component

Document both. A component's documentation should list attributes, properties, events, slots, CSS variables and parts, together.

Theme attributes

For big design changes, component libraries often combine parts with a theme switch such as variant="primary" or theme="dark" on the host, and write internal styles keyed off :host([variant="primary"]). Parts then handle the page's final touches. We cover that selector in the next lesson on host selectors and constructable stylesheets.

Parts need a shadow root

::part() looks inside the shadow tree of the element it follows, so parts are a shadow DOM feature. For components that render in the light DOM, ordinary class selectors already reach everything and no parts are needed.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How does a component expose an inner element for outside styling?

    The author marks an element with part="name" and the page selects it with host::part(name).
  2. 2. Which selector is NOT valid for parts?

    ::part() only selects the part element itself; you cannot style its descendants with a descendant combinator.
  3. 3. What does exportparts="label: chip-label" do?

    exportparts re-exposes a nested component's part, optionally under a new name.
  4. 4. Which need is best served by custom properties rather than parts?

    Simple value knobs such as colors are ideal as variables; parts handle piece-specific styling.

Summary

  • part="name" exposes an element; host::part(name) styles it from outside.
  • Only single-level selection and state pseudo-classes are allowed.
  • exportparts forwards (and can rename) parts of nested components.
  • Keep the exposed surface small; combine parts with custom properties.

Next: Host Selectors and Adopted Stylesheets