Slots and templates

Learning Objectives

• Use <template> to hold inert markup and stamp clones of it
• Distinguish named slots from the default slot, and use fallback content
• React to assignment changes with slotchange
• Tell composition from configuration when designing an element's API

<template> is inert markup

A <template> element is parsed like any other markup — the parser reads it, validates it, and builds real nodes — but it is never rendered. Its children do not go into the document tree at all. They go into a separate DocumentFragment hanging off the element's .content property, which lives outside the main tree.

That "outside the main tree" part is the whole feature, and it is more than a display trick. Scripts inside a template do not run. Images inside it do not load. Custom elements inside it are not upgraded. Nothing in there costs anything until you clone it into a tree that is actually being rendered. A <div hidden> full of markup does none of that: the browser still fetches its images and still runs its custom element definitions, it just refuses to paint the result.

To use it, clone the fragment. Always cloneNode(true) — never append .content itself. Appending a DocumentFragment moves its children out of it and leaves the fragment empty, so the first instance of your component would render and every instance after it would get nothing. Cloning keeps the template reusable, which is the reason you put the markup in a template in the first place.

The template does not have to come from the document. The demo later in this step builds one with document.createElement('template') and a string of markup, which is the usual shape when a component ships as a single JavaScript module and cannot assume the page contains anything in particular. Either way, the parse happens once and every instance clones the result.

Slots project, they do not move

This is the sentence to hold on to: a <slot> changes where a node renders, not where it lives. When you write markup inside a custom element that has a shadow root, those nodes stay exactly where you put them — in the light DOM, as children of the host element. The shadow tree declares a spot, and the browser paints them there. Nothing is moved, reparented, or copied.

Every consequence follows from that. card.children still lists what you wrote. card.querySelector('p') still finds the paragraph. Page-level CSS still styles it, because it is still an ordinary element in the ordinary document — which is exactly why step 04's ::slotted() exists at all. If slotted nodes really moved into the shadow tree, the page would have lost the ability to style them and there would be nothing for ::slotted() to do.

Named and default slots, and fallback

A shadow tree may contain one unnamed <slot>, and that one is the default: any child of the host without a slot attribute is assigned to it. Give a slot a name and a child opts in by matching it with slot="name". Children whose slot value matches no slot in the tree are assigned nowhere and simply do not render.

The <span> goes to slot="title"; the <p> has no slot attribute, so it lands in the default slot. Note that the order of the children in the markup does not have to match the order of the slots in the shadow tree — assignment is by name, and the shadow tree decides layout.

Anything you write between a slot's tags is fallback content. It renders only while nothing is assigned to that slot, and disappears the moment something is. In the template above, Untitled shows until the consumer supplies a title. Fallback is the cheapest way to make a component usable with no configuration at all, and it costs one line.

Reacting to slotchange

Slot assignment is live. A consumer can append, remove, or re-slot a child at any time, and the shadow tree has to keep up. The slotchange event fires on a slot when its set of assigned nodes changes, including the very first assignment when the element is first populated — so a listener attached in connectedCallback will hear about the initial content, not just later edits.

Two accessors read what a slot currently has. assignedElements() returns just the elements, which is what you want most of the time. assignedNodes() returns nodes, including text nodes and whitespace. Both take the same { flatten: true } option, and it does two things: it resolves nested slots — if the assigned content is itself a slot in another component's tree, flatten follows it to the real nodes — and, when nothing is assigned at all, it returns the slot's fallback content instead of an empty array. That second behavior is the one that surprises people, so keep it out of any check that is really asking "is this slot filled?".

That toggled attribute is the useful trick. The component cannot style an empty footer out of existence with CSS alone, but it can reflect "somebody gave me actions" onto the host as an attribute, and then :host(:not([has-actions])) footer { display: none; } inside the shadow tree does the rest. A slot's occupancy becomes a styling hook.

Demo: slot composition

The card below has a named title slot, a default slot for its body, and a named actions slot whose footer is hidden until something is assigned to it. Each button changes the light DOM — appending a button with slot="actions", removing them again, appending a plain paragraph — and every one of those edits produces a slotchange entry in the log. Watch which slot fires: adding a paragraph does not disturb the actions slot, and adding an action does not disturb the default one.

Composition versus configuration

Every component API is a series of decisions about which of these two an input is. Get it wrong in the configuration direction and consumers fight you with attribute values that want to be markup. Get it wrong in the composition direction and a component that should have taken a string demands three lines of boilerplate.

The two are not exclusive, and the best components use both on the same concept: a named slot for the rich case, with fallback content that renders an attribute for the simple one. Consumers who want a plain string set the attribute and never think about slots; consumers who want markup fill the slot and the fallback vanishes on its own.

Next Steps

In Step 7: Styling and theming, we'll explore:

• Designing a theming surface consumers can rely on
• Dark mode across the shadow boundary
• adoptedStyleSheets and sharing one stylesheet across every instance
• Why ::part is a versioning hazard