CSS Shadow Parts with ::part()

Technical Deep Dive & Specifications

1. The part Attribute & ::part() Pseudo-Element

The W3C CSS Shadow Parts specification allows component developers to designate specific elements within their shadow tree as explicitly styleable by consumers.

<!-- Inside Component's Shadow DOM -->
<button part="btn confirm-action">Save Changes</button>

/* In Outer Document Stylesheet */
my-dialog::part(btn) {
  padding: 10px 20px;
  font-family: inherit;
}

my-dialog::part(confirm-action) {
  background-color: #10b981;
  color: white;
}

2. Supported Pseudo-Classes on Parts

You can append pseudo-classes to ::part() to create dynamic interactive states:

/* Interactive states */
my-dialog::part(confirm-action):hover {
  background-color: #059669;
}

my-dialog::part(confirm-action):focus-visible {
  outline: 2px solid #3b82f6;
  outline-offset: 2px;
}

my-dialog::part(confirm-action):disabled {
  opacity: 0.5;
}

3. What ::part() CANNOT Do (Architectural Guardrails)

To preserve encapsulation, the specification strictly limits selector traversal past a part:

/* ❌ INVALID: Cannot target descendant children of a part! */
my-dialog::part(btn) > span { color: red; } 

/* ❌ INVALID: Cannot target adjacent siblings of a part! */
my-dialog::part(btn) + p { margin-top: 10px; }

/* ❌ INVALID: Cannot select arbitrary inner pseudo-elements! */
my-dialog::part(input)::placeholder { color: gray; }

4. Forwarding Nested Parts with exportparts

When you build composite Web Components (a component containing other custom elements inside its shadow root), the inner parts are hidden from the outer document by default. To expose them, use the exportparts attribute:

OUTER DOCUMENT
     │
     ▼ ::part(submit-btn)
┌─────────────────────────────────────────────────────────────┐
│ <search-form> (Parent Custom Element)                       │
│   #shadow-root                                              │
│     │                                                       │
│     ▼ exportparts="button: submit-btn"                      │
│   ┌───────────────────────────────────────────────────────┐ │
│   │ <custom-button part="button"> (Inner Custom Element)  │ │
│   │   #shadow-root                                        │ │
│   │     <button part="button">Search</button>             │ │
│   └───────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

Syntax Patterns for exportparts:

• exportparts="inner-part": Exports the inner part with the same name.
• exportparts="inner-part: outer-name": Renames/maps the inner part to a new public name.
• exportparts="btn: action-btn, input: search-field": Exports multiple mapped parts separated by commas.

💻 Interactive Code Playground

Starter Code

Save this file as css-parts.html and open it in your browser:

Line-by-Line Code Breakdown

• Line 115–119: Inside the shadow tree, elements are decorated with part="card-container", part="product-title", part="price-tag", and part="buy-button".
• Line 24–47: Outer CSS document targets these parts directly (product-card.theme-emerald::part(buy-button)), granting complete styling freedom over colors, typography, and borders.
• Line 32, 47: Pseudo-classes like :hover are appended directly to ::part(buy-button):hover to change interaction states.