🌓 Chapter 83: Shadow DOM

The ::slotted() Pseudo-Element

Styling projected Light DOM nodes from inside the shadow tree, the direct-child limitation, and Light DOM vs. Shadow DOM specificity rules.

LEARNING OBJECTIVES ⌵

Understand what slotted (projected) nodes are and where they reside in the DOM hierarchy.
Target projected Light DOM elements using the ::slotted(<compound-selector>) pseudo-element.
Master the Direct Child Limitation: understand why ::slotted() cannot select nested descendant children of slotted nodes.
Analyze the specificity and cascade precedence between outer Light DOM styles and internal ::slotted() styles.
Style both default and named slots across dynamic component layouts.

🎬 INTERACTIVE VISUAL PIPELINE Core Architecture Simulation

🌐

1. Input

Directives & Tags

⚙️

2. Parse

Tokenizer & AST

🌳

3. Layout

Box Model & Flow

🎨

4. Render

GPU Paint & Composite

PHASE 1: INPUT & DIRECTIVES

Browser receives declarative markup stream, parsing tag tokens and initializing component state.

📖 The Mental Model & Story (Intuitive Foundation)

Imagine a high-end picture frame displayed in an art gallery.

The Frame (Shadow Tree): Built with custom mahogany wood, glass, and internal LED spotlights.
The Artwork (Slotted Light DOM Content): Created and owned by an external artist (the parent document). The artist places their painting inside the frame's slot.
Styling with ::slotted() (The Frame's LED Spotlight): From inside the frame, the LED spotlights can cast a soft warm glow onto the direct surface of the canvas (::slotted(img) { border-radius: 4px; }).
The Limitation (Cannot Touch the Artist's Brushstrokes): The frame's lighting cannot reach inside the canvas to repaint individual paint strokes inside the painting (::slotted(div) p is invalid). Furthermore, if the artist brings their own physical varnish or ink (Light DOM CSS), the artist's styling takes precedence over the frame's lighting.

LIGHT DOM (The Artist's Painting)
┌────────────────────────────────────────────────────────┐
│  <my-card>                                             │
│    <h3 slot="title" class="artist-title">Project X</h3>│ <--- DIRECT SLOTTED NODE
│    <div slot="body">                                   │ <--- DIRECT SLOTTED NODE
│      <p>Nested child paragraph</p>                     │ <--- NESTED DESCENDANT (Untouchable by ::slotted)
│    </div>                                              │
│  </my-card>                                            │
└───────────────────────────┬────────────────────────────┘
                            │ Projected into Slot
                            ▼
SHADOW TREE (The Frame)
┌────────────────────────────────────────────────────────┐
│  #shadow-root                                          │
│    <slot name="title"></slot>                          │
│    <slot name="body"></slot>                           │
│                                                        │
│  ::slotted(h3)      ===> MATCHES direct <h3 slot="title"> │
│  ::slotted(div)     ===> MATCHES direct <div slot="body"> │
│  ::slotted(p)       ===> ❌ FAILS! (p is inside div)   │
│  ::slotted(div p)   ===> ❌ INVALID CSS SYNTAX!         │
└────────────────────────────────────────────────────────┘

Technical Deep Dive & Specifications

1. What is Content Projection?

When a custom element contains children in the Light DOM, the browser does not move them in the DOM tree. Instead, it projects them through <slot> elements into the visual Flat Tree.

<!-- Light DOM (Host Document) -->
<article-card>
  <h2 slot="headline">Breaking Technology News</h2>
</article-card>

<!-- Inside Component's Shadow DOM -->
<div class="card-wrapper">
  <slot name="headline"></slot>
</div>

2. The `::slotted()` Selector Syntax

Inside the shadow root stylesheet, you use ::slotted() to apply default styles to projected elements:

/* Styles any top-level slotted node */
::slotted(*) {
  box-sizing: border-box;
}

/* Styles top-level slotted <h2> elements */
::slotted(h2) {
  margin: 0 0 10px 0;
  font-family: var(--font-heading, sans-serif);
  color: #1e293b;
}

/* Styles top-level slotted elements having class .lead */
::slotted(.lead) {
  font-size: 1.15rem;
  color: #64748b;
}

3. The Direct-Child Restriction (Crucial Spec Rule)

According to the CSS Scoping Module Level 1 specification:

The ::slotted() pseudo-element matches only the first-level child nodes distributed to a slot. It never matches descendants of those nodes.

<!-- Light DOM -->
<user-card>
  <div class="user-info">
    <span class="user-name">Sarah Connor</span>
  </div>
</user-card>

Selector in Shadow Root	Matches?	Reason
`::slotted(.user-info)`	✅ YES	`.user-info` is the direct slotted node
`::slotted(div)`	✅ YES	Direct slotted tag matches `div`
`::slotted(.user-name)`	❌ NO	`.user-name` is a descendant inside `div`
`::slotted(div) .user-name`	❌ NO	Combinators after `::slotted()` targeting descendants are invalid
`::slotted(div > span)`	❌ NO	Argument inside `::slotted()` must be a single compound selector

4. Light DOM vs. Shadow DOM Specificity on Slotted Content

Slotted elements live in the Light DOM, which means they are subject to both Light DOM stylesheets and Shadow DOM ::slotted() styles.

Specificity Order for Slotted Elements (Lowest to Highest):
1. Shadow DOM default fallback content inside <slot>Fallback</slot>
2. Shadow DOM `::slotted(...)` styles
3. Outer Light DOM styles targeting the element (e.g. `article-card h2`)
4. Outer Light DOM styles with `!important`

[!IMPORTANT] Light DOM Always Wins: If an outer stylesheet has h2 { color: blue; } and the shadow root has ::slotted(h2) { color: red; }, the rendered text will be blue! Light DOM rules naturally override shadow ::slotted() rules unless ::slotted() uses !important.

SYS: ACTIVE

HULL: 98%

CORE: STABLE

NET: ONLINE

HTML STARSHIP CODE TERMINAL example.html

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

💻 Interactive Code Playground

Starter Code

Save this file as slotted-demo.html and open it in your browser:

Line-by-Line Code Breakdown

Line 66–71: ::slotted(img[slot="media"]) enforces image geometry (width: 100%, height: 180px, object-fit: cover) on the slotted image tag.
Line 74–78: ::slotted(h2[slot="title"]) provides baseline title typography.
Line 14–17: The outer document defines .custom-title { color: #38bdf8; }. Because outer Light DOM rules take precedence over shadow ::slotted() rules, the title text renders sky blue.
Line 81–86: ::slotted(p) formats all paragraphs projected into the default unnamed slot.

SYS: ACTIVE

HULL: 98%

CORE: STABLE

NET: ONLINE

HTML STARSHIP CODE TERMINAL playground.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Lesson 83.6 - ::slotted() Playground</title>
  <style>
    body {
      font-family: system-ui, sans-serif;
      padding: 2rem;
      background-color: #0f172a;
      color: #f8fafc;
    }

/* Light DOM Overrides */
    .custom-title {
      /* Outer document overrides will beat shadow ::slotted defaults */
      color: #38bdf8;
    }
  </style>
</head>
<body>

<h1>Slotted Content Projection & Styling</h1>

<media-card>
    
    <img slot="media" src="https://picsum.photos/400/200" alt="Mountain landscape">

<h2 slot="title" class="custom-title">Alpine Expedition 2026</h2>

<p>Join us on an unforgettable ascent through the Swiss Alps.</p>
    <p>All climbing gear and permits included.</p>

<div slot="actions" style="display: flex; gap: 8px;">
      <button style="background: #38bdf8; border: none; padding: 6px 12px; border-radius: 4px; font-weight: bold; cursor: pointer;">Register</button>
    </div>
  </media-card>

connectedCallback() {
        this.shadowRoot.innerHTML = `
          <style>
            :host {
              display: block;
              max-width: 400px;
              background-color: #1e293b;
              border-radius: 12px;
              overflow: hidden;
              box-shadow: 0 10px 25px rgba(0,0,0,0.3);
              border: 1px solid #334155;
            }

.body-container {
              padding: 1.25rem;
            }

/* 1. Style slotted image */
            ::slotted(img[slot="media"]) {
              width: 100%;
              height: 180px;
              object-fit: cover;
              display: block;
            }

/* 2. Style slotted title default */
            ::slotted(h2[slot="title"]) {
              margin: 0 0 8px 0;
              font-size: 1.3rem;
              color: #ffffff; /* Overridden by .custom-title if declared in Light DOM */
            }

/* 3. Style default slotted paragraphs */
            ::slotted(p) {
              color: #94a3b8;
              font-size: 0.9rem;
              line-height: 1.5;
              margin: 0 0 8px 0;
            }

/* 4. Slot fallback style */
            .actions-wrapper {
              margin-top: 12px;
              padding-top: 12px;
              border-top: 1px solid #334155;
            }
          </style>

<slot name="media"></slot>
          <div class="body-container">
            <slot name="title"></slot>
            <slot></slot>
            <div class="actions-wrapper">
              <slot name="actions">
                <span style="color: #64748b; font-size: 0.8rem;">No actions available</span>
              </slot>
            </div>
          </div>
        `;
      }
    }

customElements.define('media-card', MediaCard);
  </script>
</body>
</html>

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

🏋️ Hands-On Exercise

🎯 The Challenge: Build a Reusable Tab Panel with Styled Slotted Tabs

Scenario: You are building an accessible <tab-group> custom element. Consumers project their tab buttons and content panels into slots. You must use ::slotted() to format the projected elements into clean, modern UI components.

Instructions:

Create a custom element <tab-group> with an open shadow root.
In the shadow template, provide <slot name="tabs"></slot> inside a tab bar container, and <slot name="panels"></slot> inside a content area.
Use ::slotted(button[slot="tabs"]) to style tab triggers (background: transparent, border: none, color: #94a3b8, padding: 10px 16px, cursor: pointer, font-size: 14px, border-bottom: 2px solid transparent).
Use ::slotted(button[slot="tabs"][aria-selected="true"]) to highlight the active tab (color: #38bdf8, border-bottom-color: #38bdf8, font-weight: 600).
Use ::slotted(section[slot="panels"]) to style the tab panels (padding: 16px, color: #e2e8f0).

🏁 Starter Code Sandbox

SYS: ACTIVE

HULL: 98%

CORE: STABLE

NET: ONLINE

STARTER CODE SANDBOX exercise.html

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Solution 83.6 - Tab Group with Slotted Styles</title>
  <style>
    body { font-family: system-ui, sans-serif; padding: 2rem; background: #0f172a; color: #fff; }
  </style>
</head>
<body>

  <h2>Accessible Tab Group Component</h2>
  
  <tab-group id="my-tabs">
    <button slot="tabs" aria-selected="true" data-tab="0">Profile</button>
    <button slot="tabs" aria-selected="false" data-tab="1">Security</button>
    <button slot="tabs" aria-selected="false" data-tab="2">Billing</button>

    <section slot="panels" data-panel="0">Profile Settings: Change username, email, and bio.</section>
    <section slot="panels" data-panel="1" style="display: none;">Security Settings: Two-factor authentication and active sessions.</section>
    <section slot="panels" data-panel="2" style="display: none;">Billing: Invoices, payment methods, and subscription plan.</section>
  </tab-group>

  <script>
    class TabGroup extends HTMLElement {
      constructor() {
        super();
        this.attachShadow({ mode: 'open' });
      }

      connectedCallback() {
        this.shadowRoot.innerHTML = `
          <style>
            :host {
              display: block;
              max-width: 600px;
              background-color: #1e293b;
              border-radius: 8px;
              border: 1px solid #334155;
              overflow: hidden;
            }

            .tab-nav {
              display: flex;
              background-color: #0f172a;
              border-bottom: 1px solid #334155;
              padding: 0 8px;
            }

            /* Slotted tab buttons */
            ::slotted(button[slot="tabs"]) {
              background: transparent;
              border: none;
              color: #94a3b8;
              padding: 12px 18px;
              font-size: 0.9rem;
              font-family: inherit;
              cursor: pointer;
              border-bottom: 2px solid transparent;
              transition: all 0.2s ease;
            }

            ::slotted(button[slot="tabs"]:hover) {
              color: #f8fafc;
            }

            /* Slotted active tab button */
            ::slotted(button[slot="tabs"][aria-selected="true"]) {
              color: #38bdf8;
              border-bottom: 2px solid #38bdf8;
              font-weight: 600;
            }

            /* Slotted panel container */
            .panel-container {
              padding: 1.5rem;
            }

            ::slotted(section[slot="panels"]) {
              font-size: 0.95rem;
              line-height: 1.6;
              color: #cbd5e1;
            }
          </style>

          <div class="tab-nav">
            <slot name="tabs"></slot>
          </div>
          <div class="panel-container">
            <slot name="panels"></slot>
          </div>
        `;

        // Interactive tab switching logic
        const tabSlot = this.shadowRoot.querySelector('slot[name="tabs"]');
        tabSlot.addEventListener('click', (e) => {
          const btn = e.target.closest('button[slot="tabs"]');
          if (!btn) return;

          const tabs = Array.from(this.querySelectorAll('button[slot="tabs"]'));
          const panels = Array.from(this.querySelectorAll('section[slot="panels"]'));
          const targetIndex = tabs.indexOf(btn);

          tabs.forEach((t, i) => t.setAttribute('aria-selected', i === targetIndex ? 'true' : 'false'));
          panels.forEach((p, i) => p.style.display = i === targetIndex ? 'block' : 'none');
        });
      }
    }

    customElements.define('tab-group', TabGroup);
  </script>
</body>
</html>

Why this works:

::slotted(button[slot="tabs"]) targets the top-level tab buttons projected into <slot name="tabs">.
::slotted(button[slot="tabs"][aria-selected="true"]) seamlessly updates visual styles when attributes are modified dynamically.
Event delegation on the <slot> element captures bubbling events from slotted Light DOM children.

⚠️ Common Pitfalls

Trying to Style Slotted Descendants: ::slotted(div) span or ::slotted(div span) does not work. ::slotted() can only select direct children assigned to the slot.
Forgetting that Light DOM CSS beats ::slotted(): If an element inside a slot has an outer CSS rule, the outer rule will override your ::slotted() rule. Use ::slotted() for sensible defaults, not mandatory overrides.

💡 Pro Tips

Compound Selector Inside Parentheses: You can pass complex compound selectors inside ::slotted(), e.g., ::slotted(a.btn[target="_blank"]:hover).
Combine with Slot Name Attribute: Use ::slotted([slot="header"]) to explicitly target content intended for specific slots.

📌 Key Takeaways

Slotted nodes remain in the Light DOM; they are only visually projected into the shadow tree.
The ::slotted(selector) pseudo-element styles direct children assigned to a <slot>.
::slotted() cannot target nested descendants of slotted elements.
Light DOM stylesheets take precedence over shadow ::slotted() rules.
::slotted(*) is useful for setting universal base margins and box-sizing on all projected nodes.
--

⭐ LEARN: HTML 🌟 ⚔️ QUIZ BATTLE ARENA // ACTIVE

? Question 1 / 3

Given the markup `<my-card><div class="wrapper"><p>Hello</p></div></my-card>`, which selector inside the shadow root of `<my-card>` will successfully style the paragraph?

Topic: HTML Fundamentals

? Question 2 / 3

What happens if an outer document stylesheet declares `h1 { color: green; }` and a custom element's shadow root declares `::slotted(h1) { color: red; }`?

Topic: HTML Fundamentals

? Question 3 / 3

Which argument to `::slotted()` is syntactically INVALID?

Topic: HTML Fundamentals

👨‍🚀 CADET FLIGHT DOSSIER

CADET EXPLORER

📖 The Mental Model & Story (Intuitive Foundation)

Technical Deep Dive & Specifications

1. What is Content Projection?

2. The ::slotted() Selector Syntax

3. The Direct-Child Restriction (Crucial Spec Rule)

4. Light DOM vs. Shadow DOM Specificity on Slotted Content

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

🏋️ Hands-On Exercise

🎯 The Challenge: Build a Reusable Tab Panel with Styled Slotted Tabs

🏁 Starter Code Sandbox

⚠️ Common Pitfalls

💡 Pro Tips

📌 Key Takeaways

Given the markup <my-card><div class="wrapper"><p>Hello</p></div></my-card>, which selector inside the shadow root of <my-card> will successfully style the paragraph?

What happens if an outer document stylesheet declares h1 { color: green; } and a custom element's shadow root declares ::slotted(h1) { color: red; }?

Which argument to ::slotted() is syntactically INVALID?

2. The `::slotted()` Selector Syntax

Given the markup `<my-card><div class="wrapper"><p>Hello</p></div></my-card>`, which selector inside the shadow root of `<my-card>` will successfully style the paragraph?

What happens if an outer document stylesheet declares `h1 { color: green; }` and a custom element's shadow root declares `::slotted(h1) { color: red; }`?

Which argument to `::slotted()` is syntactically INVALID?