On this page:

• Shadow DOM vs light DOM
• Render light DOM children with the slot element
• Assign a light DOM child to a specific slot

Shadow DOM vs light DOM

Since the introduction of shadow DOM, we use the term "light DOM" to refer to nodes that appear in the main DOM tree.

By default, if a custom element has light DOM children in HTML, they do not render at all:

<my-element>
  <p>I won't render</p>
</my-element>

You can make them render using the <slot> element.

Render light DOM children with the slot element

To render an element's light DOM children, create a <slot> for them in the element's template. For example:

render(){
  return html`
    <div>
      <slot></slot>
    </div>
  `;
}

Light DOM children will now render in the <slot>:

<my-element>
  <p>Render me</p>
</my-element>

Arbitrarily many light DOM children can populate a single slot:

<my-element>
  <p>Render me</p>
  <p>Me too</p>
  <p>Me three</p>
</my-element>

{% include project.html folder="docs/templates/slots" openFile="my-element.js" %}

Assign a light DOM child to a specific slot

To assign a light DOM child to a specific slot, ensure that the child's slot attribute matches the slot's name attribute:

render(){
  return html`
    <div>
      <slot name="one"></slot>
    </div>
  `;
}

index.html

<my-element>
  <p slot="one">Include me in slot "one".</p>
</my-element>

• Named slots only accept light DOM children with a matching slot attribute.

For example, <slot name="one"></slot> only accepts children with the attribute slot="one".

• Light DOM children with a slot attribute will only be placed in a slot with a matching name attribute.

For example, <p slot="one">...</p> will only be placed in <slot name="one"></slot>.

Examples

my-element.js

{% include project.html folder="projects/docs/templates/namedslots/my-element.js" %}

index.html

{% include project.html folder="projects/docs/templates/namedslots/index.html" %}

{% include project.html folder="docs/templates/namedslots" openFile="my-element.js" %}

Use name, not id, to select slots.

Note that a slot's id attribute has no effect!

my-element.js

render(){
  return html`
    <div>
      <slot id="one"></slot>
    </div>
  `;
}

index.html

<my-element>
  <p slot="one">nope.</p>
  <p>ohai..</p>
</my-element>

{% include project.html folder="docs/templates/slotid" openFile="my-element.js" %}