Named Slots

Projecting Content Into Specific Regions

A named slot is a <slot name="..."> element in your Shadow DOM template. A consumer targets it by adding a matching slot="..." attribute to a light DOM child. Any element without a slot attribute goes to the default (unnamed) slot instead, if one exists.

This lets a single component expose multiple, independently-styled content regions — a common pattern for cards, dialogs, and layout components with a header/body/footer structure.

class ArticleCard extends LitElement {
  render() {
    return html`
      <article>
        <header><slot name="title"></slot></header>
        <div class="body"><slot></slot></div>
        <footer><slot name="actions"></slot></footer>
      </article>
    `;
  }
}

// Usage:
// <article-card>
//   <h2 slot="title">Article Headline</h2>
//   <p>Body paragraph goes into the default slot.</p>
//   <button slot="actions">Read More</button>
// </article-card>

Each light DOM child is routed to the matching named slot by its slot attribute; the paragraph with no slot attribute goes to the default slot.

Named Slot Syntax

<!-- In the component's Shadow DOM template -->
<slot name="header"></slot>

<!-- In the consumer's light DOM markup -->
<div slot="header">My Header</div>

• The name attribute on <slot> and the slot attribute on the light DOM element must match exactly.
• A component can have any number of named slots, plus at most one default (unnamed) slot.
• Multiple elements can share the same slot attribute value — they're all projected into that named slot together, in order.
• An element with a slot attribute that doesn't match any defined slot in the component simply doesn't render at all.

Named Slots Cheat Sheet

Common named-slot patterns for typical layout components.

Styling Individual Named Slots

The ::slotted() selector can be combined with an attribute selector to target content projected into one specific named slot differently from another.

static styles = css`
  ::slotted([slot="header"]) {
    font-weight: 700;
    font-size: 1.25rem;
  }
  ::slotted([slot="actions"]) {
    text-transform: uppercase;
  }
`;

Documenting a Component's Slot Contract

Named slots form part of your component's public API, exactly like properties and events. It's worth clearly documenting which slots exist, what kind of content each expects, and whether any are required versus optional.

Common Mistakes

• Mismatching the name on <slot> and the slot attribute value on the consumer's element (including case differences).
• Forgetting that an element with an unrecognized slot value simply disappears instead of falling back to the default slot.
• Not documenting a component's available named slots, leaving consumers to guess at the correct slot attribute values.
• Overusing named slots for content that would be simpler to expose as a plain property instead (e.g. a short label string).

Key Takeaways

• Named slots (<slot name="...">) let a component expose multiple distinct content regions.
• A consumer targets a named slot by matching its element's slot attribute to the slot's name.
• ::slotted([slot="name"]) styles content within one specific named slot.
• Named slots are part of a component's public API and deserve the same documentation as properties and events.