Web Components logo Web Components Architecture

::part and ::slotted Selectors

1. Cross-Boundary Styling Architecture

Component styling in modern web architecture requires precise traversal across encapsulation boundaries without violating isolation guarantees. The CSS Scoping Module Level 1 specification defines two targeted pseudo-elements for this exact purpose, forming a critical bridge within the broader Styling, Theming & CSS Encapsulation paradigm. This section establishes the architectural intent, mapping consumer-driven styling needs to component-internal exposure points.

Encapsulation Boundaries & Selector Scope

Shadow DOM enforces strict style isolation by default. Standard CSS selectors cannot penetrate the shadow tree, preventing accidental style collisions but also blocking legitimate customization. ::part and ::slotted act as controlled gateways:

Shadow DOM Specification Alignment

Both selectors align with the WHATWG DOM Standard and CSS Scoping Module Level 1. They operate at the computed style phase, meaning they do not mutate the DOM tree but alter the cascade resolution order. Architects must treat them as explicit API contracts rather than implementation details. Overexposing internal nodes via ::part or relying on deep ::slotted traversal violates the single-responsibility principle of component boundaries.

2. ::part Selector: Implementation & Compliance

The ::part() pseudo-element enables external stylesheets to target internal Shadow DOM nodes explicitly marked with the part attribute. Implementation requires strict adherence to naming conventions that prevent collision and maintain semantic clarity. Unlike global selectors, ::part respects encapsulation while allowing controlled style injection. Architects must balance exposure granularity with maintainability, ensuring that only stable, public-facing nodes are exposed to consumer stylesheets.

Attribute Mapping & Naming Conventions

Parts must be declared declaratively in HTML or dynamically via ElementInternals/setAttribute. Use kebab-case prefixes to namespace parts within a design system.

<!-- Component Template -->
<template id="ds-button-tpl">
 <button class="ds-button" part="host">
 <span part="icon" slot="icon"></span>
 <span part="label"><slot></slot></span>
 <span part="badge" hidden></span>
 </button>
</template>
/* Consumer Stylesheet */
ds-button::part(host) {
 background: var(--ds-surface-primary);
 border-radius: var(--ds-radius-md);
}

ds-button::part(label) {
 font-weight: 600;
 letter-spacing: 0.02em;
}

Specificity & Cascade Resolution

::part() carries a specificity of 0,0,0,1 (one pseudo-element). It does not inherit specificity from the host element. When multiple ::part rules target the same node, standard cascade rules apply: specificity → source order → importance.

Pitfall: Applying !important to ::part rules breaks consumer override capabilities. Reserve !important for internal fallbacks only.

Production Pattern: Explicit Exposure

Use ElementInternals (ES2022+) to programmatically manage part exposure without direct DOM manipulation:

class DSButton extends HTMLElement {
 static #observedAttributes = ['variant'];
 static get observedAttributes() { return [...DSButton.#observedAttributes]; }

 #internals = this.attachInternals();
 #shadow = this.attachShadow({ mode: 'open' });

 constructor() {
 super();
 const tpl = document.getElementById('ds-button-tpl');
 this.#shadow.appendChild(tpl.content.cloneNode(true));
 }

 attributeChangedCallback(name, _, newVal) {
 if (name === 'variant') {
 // Dynamically toggle part visibility/exposure
 const host = this.#shadow.querySelector('[part="host"]');
 host?.toggleAttribute('data-variant', !!newVal);
 }
 }
}
customElements.define('ds-button', DSButton);

Debugging Step: Open Chrome DevTools → Elements → Shadow DOM. Right-click a node → Toggle part attribute. Verify computed styles update without triggering full layout recalculation.

3. ::slotted Selector: Projection & Distribution

The ::slotted() pseudo-element targets distributed nodes projected into <slot> elements, operating exclusively on direct children of the slot. This constraint requires deliberate DOM structuring from component consumers. When dealing with deeply nested consumer markup, developers must reference Styling Nested Slots with ::slotted Combinators to understand flattening behavior, combinator limitations, and fallback rendering strategies. Proper implementation prevents unintended style leakage and ensures predictable layout composition.

Slot Flattening & Direct-Child Constraints

::slotted() only matches nodes that are direct children of the <slot> in the light DOM. It does not traverse into nested elements.

/* ✅ Valid: Targets direct slot children */
::slotted(span) { color: var(--ds-text-primary); }

/* ❌ Invalid: Will NOT match nested children */
::slotted(div > span) { color: red; }

Light DOM Integration Patterns

Enforce consumer markup contracts via slotchange event listeners and fallback validation.

<!-- Consumer Markup -->
<my-card>
 <h2 slot="title">Dashboard</h2>
 <p slot="content">Analytics overview</p>
</my-card>
/* Component Internal Styles */
::slotted([slot="title"]) {
 margin: 0;
 font-size: var(--ds-font-xl);
}

::slotted([slot="content"]) {
 line-height: 1.5;
 padding: var(--ds-space-md) 0;
}

Fallback Content Handling

Slots render fallback content when no light DOM is provided. ::slotted() does not apply to fallback nodes. Style fallbacks directly in the component template.

Debugging Step:

  1. Inspect the <slot> element in DevTools.
  2. Check the assignedNodes() array via console: document.querySelector('slot[name="title"]').assignedNodes().
  3. If empty, fallback renders. If populated, verify ::slotted() matches only top-level assigned nodes. Use slotchange to log distribution lifecycle.

4. Theme Integration & Token-Driven Workflows

Cross-boundary selectors handle structural targeting, but value propagation relies on CSS custom properties. Integrating ::part and ::slotted with CSS Variables & Custom Properties creates a decoupled theming layer where tokens drive visuals and pseudo-elements drive layout. This separation enables single-intent workflows: selectors define where styles apply, while variables define what styles apply. Architects should enforce strict token naming conventions and boundary-aware scoping to prevent cascade collisions.

Custom Properties as Value Carriers

Custom properties inherit across shadow boundaries by default, making them ideal for token propagation.

/* Global Theme */
:root {
 --ds-color-accent: #0055ff;
 --ds-radius-pill: 9999px;
}

/* Component Internal */
::part(host) {
 background: var(--ds-color-accent);
 border-radius: var(--ds-radius-pill);
}

/* Consumer Override */
ds-button {
 --ds-color-accent: #ff4400;
}

Boundary-Aware Token Propagation

To prevent token leakage, scope variables to the host element and explicitly inherit them internally.

:host {
 --_internal-spacing: var(--ds-spacing, 1rem);
}

::part(container) {
 padding: var(--_internal-spacing);
}

Design System API Contracts

Document exposed parts and required tokens in a machine-readable format (e.g., JSON schema or Web Component Manifest). Enforce versioning to avoid breaking consumer styles when parts are renamed or removed.

Pitfall: Relying on ::part for layout shifts instead of custom properties causes layout thrashing. Use ::part for structural hooks (e.g., ::part(wrapper)), and custom properties for dimensions, colors, and typography.

5. Performance Optimization & Production Tradeoffs

Overusing cross-boundary selectors introduces measurable performance overhead due to style recalculation and layout invalidation. Production implementations must prioritize ::part for stable internal nodes and reserve ::slotted for explicit projection points. When combined with Theme Inheritance & Light DOM Styling, teams must evaluate inheritance chains against encapsulation overhead to maintain 60fps rendering pipelines. Tradeoffs include increased CSS bundle size versus reduced JavaScript styling logic, requiring careful profiling in real-world environments.

Style Recalculation & Layout Thrashing

Each ::part or ::slotted rule forces the browser to traverse the shadow tree during style resolution. Excessive usage increases Recalculate Style time in the rendering pipeline.

Optimization Technique:

Selector Specificity vs. Maintainability

High-specificity ::part chains (::part(wrapper) > ::part(inner)) are invalid per spec. ::part only accepts a single identifier. Flatten your part hierarchy:

/* ❌ Invalid */
::part(wrapper)::part(inner) { ... }

/* ✅ Valid */
::part(wrapper-inner) { ... }

Constructable Stylesheet Integration

Leverage adoptedStyleSheets for framework-agnostic, high-performance style injection.

const sheet = new CSSStyleSheet();
sheet.replaceSync(`
 :host { display: block; }
 ::part(host) { transition: transform 0.2s ease; }
`);

class OptimizedComponent extends HTMLElement {
 constructor() {
 super();
 const shadow = this.attachShadow({ mode: 'open' });
 shadow.adoptedStyleSheets = [sheet];
 shadow.innerHTML = `<div part="host"><slot></slot></div>`;
 }
}

Debugging Step: Open DevTools → Performance → Record. Filter by Layout and Recalculate Style. If ::part rules trigger frequent invalidations, move static styles to adoptedStyleSheets and isolate dynamic tokens to CSS variables.

6. Testing Strategies & Single-Intent Developer Workflows

Automated testing for cross-boundary styles requires environments that accurately simulate Shadow DOM projection and slot distribution. Single-intent developer workflows dictate that each selector serves one explicit purpose: ::part for internal component customization, ::slotted for consumer-provided content styling, and custom properties for value injection. Implement computed style assertions, snapshot testing, and visual regression pipelines to validate boundary interactions. CI/CD integration should enforce strict linting rules for selector specificity and part attribute exposure.

Headless Browser Shadow DOM Simulation

Playwright and Puppeteer natively support shadow DOM traversal. Avoid DOM-parsing workarounds; use native selectors.

// Playwright Test
import { test, expect } from '@playwright/test';

test('::part styling applies correctly', async ({ page }) => {
 await page.setContent(`
 <my-component>
 <span slot="label">Test</span>
 </my-component>
 <style>
 my-component::part(host) { background: red; }
 my-component::slotted([slot="label"]) { color: white; }
 </style>
 `);

 const host = page.locator('my-component').locator('::part(host)');
 await expect(host).toHaveCSS('background-color', 'rgb(255, 0, 0)');
});

Computed Style Assertions

Validate that tokens resolve correctly across boundaries.

async function assertTokenResolution(page, selector, token, expected) {
 const value = await page.evaluate((sel, tok) => {
 const el = document.querySelector(sel);
 return getComputedStyle(el).getPropertyValue(tok).trim();
 }, selector, token);
 
 expect(value).toBe(expected);
}

Visual Regression & Snapshot Pipelines

Integrate Percy or Chromatic with CI/CD. Configure snapshot diffing to ignore dynamic tokens (e.g., --ds-theme-mode) while asserting structural ::part boundaries.

CI/CD Linting Rule (stylelint):

{
 "rules": {
 "selector-pseudo-element-no-unknown": [true, { "ignorePseudoElements": ["part", "slotted"] }],
 "selector-max-specificity": "0,2,0",
 "declaration-no-important": true
 }
}

Pitfall: Snapshot tests fail when ::slotted content changes height/width. Use contain: size on slotted containers during testing to stabilize layout dimensions.

By adhering to these patterns, teams can build scalable, framework-agnostic component libraries that balance encapsulation with consumer flexibility, ensuring predictable styling across complex application architectures.