Skip to content
Tutorials Center
My learning

Topics

Lesson 18 of 39 ยท Templates and Slots

Slots: Passing Content into Components

Use the slot element to let page authors pass content into a shadow tree. Learn the default slot, fallback content, how slotting works, and what stays in the light DOM.

A component that renders only its own markup is not very reusable. A card needs your title, a dialog needs your message, a tab needs your content. Slots are the mechanism that lets the user of a component put content into designated places inside its shadow tree, using ordinary HTML children.

The default slot

Place a <slot> element in the shadow tree. Any light DOM children of the host that are not assigned to a named slot are rendered at that spot.

The default slot

The page author wrote normal HTML as children. The component's frame wraps it. Nothing was copied: the nodes are still the host's children in the light DOM, only rendered at the slot's position. This distinction has practical consequences:

  • host.children still lists the <h3> and <p>.
  • Page CSS still applies to slotted nodes, because they live in the page's tree. Page authors can style fancy-frame h3 { ... } from the outside.
  • Event listeners and scripts on slotted nodes keep working.

The flat tree

The browser draws what is called the flat tree: the shadow tree with each <slot> replaced by the nodes assigned to it.

flowchart TB
  subgraph Light["Light DOM (written by page author)"]
    H3["h3"]
    P["p"]
  end
  subgraph Shadow["Shadow tree (written by component)"]
    F["div.frame"]
    S["slot"]
  end
  F --> S
  H3 -.assigned to.-> S
  P -.assigned to.-> S

Slotted nodes keep their place in the light DOM but are rendered where the slot is.

Fallback content

What if the author passes nothing? Put content inside the <slot> element, and it shows only when no node is assigned.

Slot fallback

The second tag is empty, so the fallback Anonymous shows. Note a subtle rule: whitespace-only text nodes count as assigned content in some cases. An element written as <user-name> </user-name> (a single space) has a text node and may suppress the fallback in current browsers, while a fully empty one shows it. Write <user-name></user-name> with nothing between the tags when you want the fallback.

What can be slotted?

Any node that is a direct child of the host: elements and text nodes. A grandchild is not slotted separately; it moves along with its parent. Elements assigned to a slot keep all their own descendants.

Shadow roots are not slotted into other shadow roots automatically, but you can nest components: a <slot> inside component A's shadow tree can itself be slotted into by component B, forming a chain.

Reading assigned nodes

A <slot> knows which nodes were assigned to it:

JavaScript
const slot = this.shadowRoot.querySelector("slot");
slot.assignedNodes();                    // text and elements
slot.assignedElements();                 // elements only
slot.assignedNodes({ flatten: true });   // also resolves nested slots and fallback

Conversely, each slotted node reports its slot through node.assignedSlot (it is null when the root is closed or there is no slot).

Inspecting assignment

The numbers can differ between parsers and whitespace, so count only elements with assignedElements() when you need a reliable value. One quirk: calling assignedNodes() in connectedCallback when the component is defined early may return an incomplete list, because the parser has not yet created all children. The next lessons show how to wait for them with slotchange.

Slots versus attributes

Use slots for content that is markup or rich text (headings, links, images, nested components). Use attributes or properties for short configuration values (a size, a variant, a number). A button's label is typically a slot; its size="large" is an attribute. Slots keep content in the light DOM, so it remains accessible, indexable and styleable by the page, and works without JavaScript.

Common mistakes

  • Expecting a slot to copy content. It does not clone. A node can only be assigned to one slot at a time.
  • Putting the same name on two slots. Only the first one in tree order receives the nodes (details in the named slots lesson).
  • Hiding the slot's wrapper with display: none but still expecting assignedNodes to be empty; assignment is unaffected by CSS.
  • Using a slot in a light-DOM component. <slot> has no special effect outside a shadow tree.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where do the children you write inside <my-card>...</my-card> live?

    Slotting changes where nodes are drawn, not where they live in the DOM.
  2. 2. When does fallback content inside a slot show?

    Fallback content is displayed only if the slot receives no assigned nodes.
  3. 3. Which method returns only the elements assigned to a slot?

    assignedElements() filters out text nodes; children would return the fallback content instead.
  4. 4. Can page CSS style slotted elements?

    Slotted nodes belong to the light DOM, so page selectors still match them.

Summary

  • A <slot> in a shadow tree renders the host's light DOM children at its position.
  • Content inside <slot> is fallback, used only when nothing is assigned.
  • Slotted nodes stay in the light DOM, so page CSS, scripts and accessibility still work for them.
  • assignedNodes, assignedElements and assignedSlot expose the relationship.
  • Use slots for rich content and attributes for small settings.

Next: Named Slots