Michael Samuel Naeem

Encapsulation with Shadow DOM

By Michael Samuel Naeem · March 19, 2026 · 11 min read

Engineering
Share on LinkedIn Share on X Share on Reddit Share on HN Share on Bluesky

title: "Encapsulation with Shadow DOM" slug: "web-components-shadow-dom" description: "Use Shadow DOM for web component encapsulation: open vs closed mode, styling strategies, slot composition, event retargeting, and when shadow DOM helps versus hurts." datePublished: "2026-03-19" dateModified: "2026-07-17" tags:

title: "web-components-shadow-dom" slug: "web-components-shadow-dom" description: "" datePublished: "2026-07-17" dateModified: "2026-07-17" tags:

title: "web-components-shadow-dom" slug: "web-components-shadow-dom" description: "" datePublished: "2026-07-17" dateModified: "2026-07-17" tags:

title: "web-components-shadow-dom" slug: "web-components-shadow-dom" description: "" datePublished: "2026-07-17" dateModified: "2026-07-17" tags:

title: "web-components-shadow-dom" slug: "web-components-shadow-dom" description: "" datePublished: "2026-07-17" dateModified: "2026-07-17" tags:

title: "web-components-shadow-dom" slug: "web-components-shadow-dom" description: "" datePublished: "2026-07-17" dateModified: "2026-07-17" tags:

title: "Encapsulation with Shadow DOM" slug: "web-components-shadow-dom" description: "Use Shadow DOM for web component encapsulation: open vs closed mode, styling strategies, slot composition, event retargeting, and when shadow DOM helps versus hurts." datePublished: "2026-03-19" dateModified: "2026-07-17" tags:

I shipped a widget library without Shadow DOM. Three months later, a consumer's global CSS rule div { margin: 16px } broke layout in every component. We added a prefix to every class name. Then their Tailwind reset removed our list styles. Then their !important theme overrode our button colors. We spent more time fighting style collisions than building features. Shadow DOM would have prevented all of it by scoping styles inside an isolated subtree. It's not free — it complicates testing, theming, and SSR — but for reusable components distributed across unknown host pages, encapsulation is worth the trade-off.

Creating a shadow root

class UserCard extends HTMLElement {
  constructor() {
    super();
    const shadow = this.attachShadow({ mode: 'open' });
    shadow.innerHTML = `
      <style>
        .card { padding: 1rem; border: 1px solid #e5e7eb; border-radius: 8px; }
        .name { font-size: 1.25rem; font-weight: 600; }
        .email { color: #6b7280; }
      </style>
      <div class="card">
        <div class="name"><slot name="name">Unknown</slot></div>
        <div class="email"><slot name="email"></slot></div>
      </div>
    `;
  }
}

customElements.define('user-card', UserCard);

<user-card>
  <span slot="name">Alice Chen</span>
  <span slot="email">[email protected]</span>
</user-card>

External CSS cannot affect .card, .name, or .email inside the shadow tree. Internal styles don't leak out.

Open vs closed mode

// Open (recommended): shadowRoot is accessible
this.attachShadow({ mode: 'open' });

// Closed: shadowRoot returns null
this.attachShadow({ mode: 'closed' });

Use open mode. Closed mode breaks:

Slots: composable content

Slots project light DOM content into shadow DOM positions:

<!-- Component definition -->
<template id="card-tmpl">
  <style>
    header { font-weight: bold; }
    ::slotted(img) { max-width: 100%; border-radius: 4px; }
  </style>
  <header><slot name="title">Default Title</slot></header>
  <div class="body"><slot>Default body content</slot></div>
  <footer><slot name="footer"></slot></footer>
</template>

<!-- Usage -->
<my-card>
  <span slot="title">Product Name</span>
  <p>Product description here.</p>
  <span slot="footer">$29.99</span>
</my-card>

Styling strategies

Encapsulated (default)

Styles inside shadow DOM scope to the component. No collisions.

CSS custom properties for theming

The escape hatch for host-page theming:

/* Inside shadow DOM */
.card {
  background: var(--card-bg, white);
  color: var(--card-text, #1f2937);
  border-color: var(--card-border, #e5e7eb);
}

/* On the host page */
user-card {
  --card-bg: #1e293b;
  --card-text: #f1f5f9;
  --card-border: #334155;
}

Custom properties pierce shadow boundaries. This is the standard theming contract for web components.

::part() for targeted styling

Expose specific shadow elements for external styling:

/* Inside shadow DOM */
.button { /* internal styles */ }

<button class="button" part="button">Click</button>

/* On the host page */
user-card::part(button) {
  background: #2563eb;
  border-radius: 999px;
}

:host styles the custom element itself from inside shadow DOM:

:host { display: block; }
:host([disabled]) { opacity: 0.5; pointer-events: none; }
:host-context(.dark-theme) { color: white; }

Event retargeting

Events that originate inside shadow DOM are retargeted at the host element:

const card = document.querySelector('user-card');
card.addEventListener('click', (e) => {
  console.log(e.target);    // user-card (not the internal button)
  console.log(e.composedPath()); // [button, shadow-root, user-card, ...]
});

For events that need to escape shadow DOM, set composed: true:

this.dispatchEvent(new CustomEvent('select', {
  detail: { id: this.itemId },
  bubbles: true,
  composed: true  // crosses shadow boundary
}));

When to use shadow DOM

Use it:

Skip it:

Testing shadow DOM components

// Open mode: query inside shadow root
const card = document.querySelector('user-card');
const name = card.shadowRoot.querySelector('.name');
expect(name.textContent).toBe('Alice Chen');

// Playwright: pierce shadow
const button = page.locator('user-card').locator('.button');
await button.click();

For closed mode, testing requires the component to expose test hooks — another reason to prefer open mode.

constructable stylesheets at scale

Share one adopted stylesheet across component instances:

const sheet = new CSSStyleSheet();
await sheet.replace(stylesText);
class DsCard extends HTMLElement {
  connectedCallback() {
    this.shadowRoot.adoptedStyleSheets = [sharedSheet];
  }
}

Reduces memory vs inline <style> per instance on pages with hundreds of cards.

Slot change events

Listen for slotted content changes:

const slot = this.shadowRoot.querySelector('slot');
slot.addEventListener('slotchange', () => {
  const nodes = slot.assignedNodes({ flatten: true });
  this._updateFromSlottedContent(nodes);
});

Dynamic slotted forms need slotchange handlers to wire up labels and validation.

Light DOM CSS piercing for legacy

When migrating from non-shadow components, document which global CSS rules must become --token variables or ::part() exposures—grep host app stylesheets for component tag selectors before enabling shadow.

Practical follow-through (1)

Ship the smallest vertical slice first — one route, one widget, one index configuration — with rollback documented before expanding scope. Baseline the user-visible metric this work protects (latency, recall, conversion, task success rate) for seven days before change and seven days after in your largest market.

Compare canary p75 to control before full rollout. Exercise edge paths manually: refresh, back navigation, double-submit, offline mode, and keyboard-only flows. When assumptions change — traffic doubles, vendor upgrades, org restructure — revisit whether the original design still fits; quiet periods hide drift until the next incident.

Practical follow-through (2)

Ship the smallest vertical slice first — one route, one widget, one index configuration — with rollback documented before expanding scope. Baseline the user-visible metric this work protects (latency, recall, conversion, task success rate) for seven days before change and seven days after in your largest market.

Compare canary p75 to control before full rollout. Exercise edge paths manually: refresh, back navigation, double-submit, offline mode, and keyboard-only flows. When assumptions change — traffic doubles, vendor upgrades, org restructure — revisit whether the original design still fits; quiet periods hide drift until the next incident.

Practical follow-through (3)

Ship the smallest vertical slice first — one route, one widget, one index configuration — with rollback documented before expanding scope. Baseline the user-visible metric this work protects (latency, recall, conversion, task success rate) for seven days before change and seven days after in your largest market.

Compare canary p75 to control before full rollout. Exercise edge paths manually: refresh, back navigation, double-submit, offline mode, and keyboard-only flows. When assumptions change — traffic doubles, vendor upgrades, org restructure — revisit whether the original design still fits; quiet periods hide drift until the next incident.

Practical follow-through (4)

Ship the smallest vertical slice first — one route, one widget, one index configuration — with rollback documented before expanding scope. Baseline the user-visible metric this work protects (latency, recall, conversion, task success rate) for seven days before change and seven days after in your largest market.

Compare canary p75 to control before full rollout. Exercise edge paths manually: refresh, back navigation, double-submit, offline mode, and keyboard-only flows. When assumptions change — traffic doubles, vendor upgrades, org restructure — revisit whether the original design still fits; quiet periods hide drift until the next incident.

Resources

Frequently asked questions

What is the main production risk with web components shadow dom?

Teams ship without field measurement—web components shadow dom failures appear as silent UX regressions, cost drift, or audit findings rather than clear errors.

When should we prioritize web components shadow dom?

Prioritize when user research, CrUX, support tickets, or compliance requirements show pain on critical paths—not when a checklist mentions it abstractly.

How do we validate web components shadow dom changes?

Baseline RUM before changes, compare p75 after deploy, and keep rollback via feature flags or cache purge documented in the PR.

Hiring a senior Android / Flutter engineer?

I architect and ship production mobile software — Kotlin, Jetpack Compose, Flutter — for robotics, EV infrastructure, fintech, and real-time systems. Open to remote roles in Europe and the US.

Get in touch →