Pass Markup into Slots

Add a slot to a component’s HTML file so a parent component can pass markup into the component. A component can have zero or more slots.

A slot (<slot></slot>) is a placeholder for markup that a parent component passes into a component’s body.

You can’t pass an Aura component into a slot. If you nest a Lightning web component in an Aura component, you also can’t pass it into a slot.

Important

To use slots as drop regions in Experience Builder for an LWR site, see Create Custom Layout Components in the LWR Sites for Experience Cloud guide.

Note

Unnamed Slots

This example has an unnamed slot. An unnamed slot uses the <slot> element as a placeholder for any markup that a parent component passes into the body of c-slot-demo.

1<!-- slotDemo.html -->
2<template>
3  <h1>Add content to slot</h1>
4  <div>
5    <slot></slot>
6  </div>
7</template>

Here’s the markup for a parent component that uses c-slot-demo.

1<!-- slotWrapper.html -->
2<template>
3  <c-slot-demo>
4    <p>content from parent</p>
5  </c-slot-demo>
6</template>

When c-slot-demo is rendered, the unnamed slot is replaced with the markup passed into the body of c-slot-demo. Here’s the rendered output of c-slot-wrapper.

1<h1>Add content to slot</h1>
2<div>
3  <slot>
4    <p>content from parent</p>
5  </slot>
6</div>

If a component has more than one unnamed slot, the markup passed into the body of the component is inserted into all the unnamed slots. However, a component usually has zero or one unnamed slot.

Named Slots

This example component has two named slots and one unnamed slot.

1<!-- namedSlots.html -->
2<template>
3  <p>First Name: <slot name="firstName">Default first name</slot></p>
4  <p>Last Name: <slot name="lastName">Default last name</slot></p>
5  <p>Description: <slot>Default description</slot></p>
6</template>

You can set a dynamic value for the slot attribute of an HTML element. Here, the <span> element has a slot attribute set to the variable dynamicName.

1<template>
2  <c-item>
3    <span slot={dynamicName}></span>
4  </c-item>
5</template>

The dynamic value passed into the slot attribute is coerced to a string. For example, if you pass the number 4 to the attribute, it is converted to the string "4". If you pass in a data type that can’t be converted into a string, such as a Symbol(), a TypeError is thrown.

This change doesn’t impact attributes of <slot> elements. For example, you still must pass a static string into the attribute name for a <slot> element.

1<template>
2  <slot name="”staticName”"> </slot>
3</template>

Here’s the markup for a parent component that uses c-named-slots.

1<!-- slotsWrapper.html -->
2<template>
3  <c-named-slots>
4    <span slot="firstName">Willy</span>
5    <span slot="lastName">Wonka</span>
6    <span>Chocolatier</span>
7  </c-named-slots>
8</template>

The c-slots-wrapper component passes:

Willy into the firstName slot
Wonka into the lastName slot
Chocolatier into the unnamed slot

Here’s the rendered output.

1<c-named-slots>
2  <p>
3    First Name:
4    <slot name="firstName"><span slot="firstName">Willy</span></slot>
5  </p>
6  <p>
7    Last Name:
8    <slot name="lastName"><span slot="lastName">Wonka</span></slot>
9  </p>
10  <p>
11    Description:
12    <slot><span>Chocolatier</span></slot>
13  </p>
14</c-named-slots>

Access Elements Passed Via Slots

The <slot></slot> element is part of a component’s shadow tree. To access elements in its shadow tree, a component calls this.template.querySelector() and this.template.querySelectorAll().

However, the DOM elements that are passed into the slot aren’t part of the component’s shadow tree. To access elements passed via slots, a component calls this.querySelector() and this.querySelectorAll().

This example shows how to pass DOM elements to a child component from the child’s context. Provide the selector name, such as an element, for this.querySelector() and this.querySelectorAll().

1// namedSlots.js
2import { LightningElement } from "lwc";
3
4export default class NamedSlots extends LightningElement {
5  renderedCallback() {
6    this.querySelector("span"); // <span>push the green button.</span>
7    this.querySelectorAll("span"); // [<span>push the green button</span>, <span>push the red button</span>]
8  }
9}

In this example, the querySelector accepts the element span.

Don’t pass an id to a query method like querySelector. When an HTML template is rendered, id values can be transformed into globally unique values. If you use an id selector in JavaScript, it doesn’t match the transformed id.

Note

Render Slots Conditionally

To render a slot conditionally, nest the slot in a <template> tag with the lwc:if, lwc:else, and/or lwc:elseif directives.

1<template>
2  <template lwc:if={expression}>
3    <div class="my-class">
4      <slot></slot>
5    </div>
6  </template>
7  <template lwc:else>
8    <slot></slot>
9  </template>
10</template>

The template compiler treats the conditional directives as a valid use case, and it knows that <slot> isn’t rendered twice.

If you use the legacy if:true and if:false directives, the compiler warns you about duplicate slots because it’s not clear if <slot> will only render once. For example, the expression getter can have an inconsistent return value each time.

Run Code on slotchange

All <slot> elements support the slotchange event. The slotchange event fires when a direct child of a node in a <slot> element changes. For example, this occurs when new content is appended or deleted. Only <slot> elements support this event.

Changes within the children of the <slot> element don’t trigger a slotchange event.

In this example, the <slot> element handles the slotchange event.

1<!-- container.html -->
2<template>
3  <slot onslotchange={handleSlotChange}></slot>
4</template>

1// container.js
2handleSlotChange (e) {
3   console.log("New slotted content has been added or removed!");
4}

The component c-child is passed into the slot.

1<c-container>
2  <c-child></c-child>
3  <template lwc:if={addOneMore}>
4    <c-child></c-child>
5  </template>
6</c-container>

If the flag addOneMore is set to True, the console prints the first time the component is rendered.

1<!-- child.html -->
2<template>
3  <button onclick={handleClick}>Toggle Footer</button>
4  <template lwc:if={showFooter}>
5    <footer>Footer content</footer>
6  </template>
7</template>

The slotchange event is not triggered even if showFooter is true and the footer element is appended.

See Also