<slot>

This is an experimental technology
Because this technology's specification has not stabilized, check the compatibility table for usage in various browsers. Also note that the syntax and behavior of an experimental technology is subject to change in future versions of browsers as the specification changes.

The HTML <slot> element—part of the Web Components technology suite—is a placeholder inside a web component that you can fill with your own markup, which lets you create separate DOM trees and present them together.

Content categories Flow content, phrasing content
Permitted content Transparent
Tag omission None, both the starting and ending tag are mandatory.
Permitted parents Any element that accepts phrasing content
Permitted ARIA roles None
DOM interface HTMLSlotElement

Attributes

This element includes the global attributes.

name
The slot's name.
A named slot is a <slot> element with a name attribute.

Example

Let’s make an example using the <slot> element along with the <template> element.

Partnering <slot> with <template>

The following set of code snippets show how to use the <slot> element together with the <template> element and some JavaScript to:

  • create a <element-details> element with named slots in its shadow root
  • design the <element-details> element in such a way that, when used in documents, it is rendered from composing the element’s content together with content from its shadow root—that is, pieces of the element’s content are used to fill in named slots in its shadow root

Use <slot> in <template> to make a doc fragment with named slots

First let’s use the <slot> element within a <template> element to create a new “element-details-template” document fragment containing some named slots.

<template id="element-details-template">
  <style>
  details {font-family: "Open Sans Light",Helvetica,Arial}
  .name {font-weight: bold; color: #217ac0; font-size: 120%}
  h4 { margin: 10px 0 -8px 0; }
  h4 span { background: #217ac0; padding: 2px 6px 2px 6px }
  h4 span { border: 1px solid #cee9f9; border-radius: 4px }
  h4 span { color: white }
  .attributes { margin-left: 22px; font-size: 90% }
  .attributes p { margin-left: 16px; font-style: italic }
  </style>
  <details>
    <summary>
      <span>
        <code class="name">&lt;<slot name="element-name">NEED NAME</slot>&gt;</code>
        <i class="desc"><slot name="description">NEED DESCRIPTION</slot></i>
      </span>
    </summary>
    <div class="attributes">
      <h4><span>Attributes</span></h4>
      <slot name="attributes"><p>None</p></slot>
    </div>
  </details>
  <hr>
</template>

That <template> element has several features:

Create a new <element-details> element from a <template> element

Next, let’s create a new custom element named <element-details> and use Element.attachShadow to attach to it, as its shadow root, that document fragment we created with our <template> element above.

customElements.define('element-details',
  class extends HTMLElement {
    constructor() {
      super();
      var template = document
        .getElementById('element-details-template')
        .content;
      const shadowRoot = this.attachShadow({mode: 'open'})
        .appendChild(template.cloneNode(true));
  }
})

Use the <element-details> custom element with named slots

Now let’s take that <element-details> element and actually use it in our document.

<element-details>
  <span slot="element-name">slot</span>
  <span slot="description">A placeholder inside a web
    component that users can fill with their own markup,
    with the effect of composing different DOM trees
    together.</span>
  <dl slot="attributes">
    <dt>name</dt>
    <dd>The name of the slot.</dd>
  </dl>
</element-details>
<element-details>
  <span slot="element-name">template</span>
  <span slot="description">A mechanism for holding client-
    side content that is not to be rendered when a page is
    loaded but may subsequently be instantiated during
    runtime using JavaScript.</span>
</element-details> 

About that snippet, notice these points:

  • The snippet has two instances of <element-details> elements which both use the slot attribute to reference the named slots "element-name" and "description" we put in the <element-details> shadow root .
  • Only the first of those two <element-details> elements references the "attributes" named slot. The second <element-details> element lacks any reference to the "attributes" named slot.
  • The first <element-details> element references the "attributes" named slot using a <dl> element with <dt> and <dd> children.

Add a final bit of style

Finishing touch: A tiny bit more CSS for the <dl>, <dt>, and <dd> elements in our doc.

  dl { margin-left: 6px; }
  dt { font-weight: bold; color: #217ac0; font-size: 110% }
  dt { font-family: Consolas, "Liberation Mono", Courier }
  dd { margin-left: 16px }

Result

Finally let’s put all the snippets together and see what the rendered result looks like.

ScreenshotLive sample

About that rendered result, notice these points:

  • Even though the instances of the <element-details> element in the document do not directly use the <details> element, they get rendered using <details> because the shadow root causes them to get populated with that.
  • Within the rendered <details> output, the content in the <element-details> elements  fills the named slots from the shadow root. In other words, the DOM tree from the <element-details> elements get composed together with the content of the shadow root.
  • For both <element-details> elements, an Attributes heading gets automatically added from the shadow root before the position of the "attributes" named slot.
  • Because the first <element-details> has a <dl> element which explicitly references the "attributes" named slot from its shadow root, the contents of that <dl> replace the "attributes" named slot from the shadow root.
  • Because the second <element-details> doesn’t explicitly reference the "attributes" named slot from its shadow root, its content for that named slot gets filled with the default content for it from the shadow root.

Specifications

Specification Status Comment
WHATWG HTML Living Standard
The definition of '<slot>' in that specification.
Living Standard  
DOM
The definition of 'Slots' in that specification.
Living Standard  

Browser compatibility

Feature Chrome Edge Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Basic support 53 ? ? ? 40 10
Feature Android Edge Firefox Mobile (Gecko) IE Phone Opera Mobile Safari Mobile
Basic support 53 ? ? ? 40 10.1

Document Tags and Contributors

 Contributors to this page: chrisdavidmills, sideshowbarker, Sheppy, Hfmanson
 Last updated by: chrisdavidmills,