Skip to content
Tutorials Center
My learning

Topics

Lesson 26 of 87 ยท Components

Slots

Pass markup into components with Vue slots. Learn default and named slots, fallback content, scoped slots, dynamic slot names and renderless components, with live examples.

Props let a parent hand data to a child. Sometimes the parent needs to hand over something bigger: a piece of markup. A card needs a body, a dialog needs a title and some buttons, a table needs a custom cell. Writing a prop for every possible piece of HTML would be clumsy, so Vue gives components slots: placeholders where the parent's template content is inserted.

A slot turns a component from "a box that shows your data" into "a box you can fill". It is the main tool for building layout components, wrappers and reusable widgets. In this lesson you will use the default slot, fallback content, named slots, scoped slots (where the child passes data back up to the slot content), dynamic slot names and the renderless component pattern. It builds on Components Basics and Events and emits, and the same idea is called "children" in React (Children and Composition).

Single-file components (.vue files) are shown as read-only blocks, because the site runs no build step. Every live example uses the same component written as a template string, which Vue compiles in the browser. The examples load the full browser build of Vue 3.5.13 from jsDelivr, because the plain runtime build cannot compile template strings.

The default slot

Put a <slot> element in the child's template. Whatever the parent writes between the component's opening and closing tags is rendered in that spot.

flowchart LR
  P["Parent template<br/>&lt;BaseCard&gt;<br/>hello<br/>&lt;/BaseCard&gt;"] -->|"content"| S["slot outlet in BaseCard"]
  S --> R["Rendered card with 'hello' inside"]

The parent writes the content, the child decides where it appears.

Here is the same idea as a .vue file (read-only):

HTML
<!-- BaseCard.vue (read-only) -->
<script setup>
defineProps({ title: String })
</script>

<template>
  <section class="card">
    <h3>{{ title }}</h3>
    <slot>Nothing here yet.</slot>
  </section>
</template>

The text inside <slot>...</slot> is fallback content. It is rendered only when the parent passes nothing. That makes a component usable with zero configuration while still letting you override the default. The live version below shows both cases: one card with content, one without.

Default slot and fallback content

Slot content can be anything: plain text, HTML, other components, even directives such as v-if. It is compiled in the parent's scope, so it can use the parent's data and methods but not the child's. This rule trips up many beginners, and scoped slots (below) are the official way around it.

Named slots

One slot is often not enough. A panel might want a header, a body and a footer. Give each extra outlet a name, and in the parent wrap the matching content in a <template> with a v-slot directive. The shorthand for v-slot:header is #header. Content that is not wrapped goes to the unnamed (default) slot.

flowchart TB
  subgraph Parent
    A["template #header"]
    B["loose content"]
    C["template #footer"]
  end
  subgraph Panel["Panel component"]
    X["slot name=header"]
    Y["slot (default)"]
    Z["slot name=footer"]
  end
  A --> X
  B --> Y
  C --> Z

Each <template #name> block is routed to the outlet with the same name.

A component can check which slots the parent actually filled through $slots in the template (or useSlots() in <script setup>). That lets you skip empty wrappers, such as a footer with padding and a border but nothing in it.

Named slots and $slots checks

Dynamic slot names

The slot name in v-slot can be an expression in square brackets, just like dynamic attribute names. You rarely need it, but it is handy for generic components (tab panels, table columns) where the slot name comes from data. In the example, one button decides which side of a two-column layout receives the note.

Dynamic slot names

Scoped slots

Slot content normally cannot see the child's data. But what if the child owns a list and the parent wants to decide how each row looks? The child can pass values to the slot outlet as attributes. These are called slot props. The parent receives them with v-slot="{ ... }" (destructuring works as it does for function parameters).

sequenceDiagram
  participant P as Parent
  participant C as ItemList (child)
  P->>C: items prop and a slot template
  loop for each item
    C->>P: slot props: item, index
    P-->>C: rendered row markup
  end

Props flow down as usual; slot props flow from the child's outlet into the parent's slot template.

In effect, a scoped slot is a function that the parent supplies and the child calls with arguments. This is why the technique is so powerful: the child controls the iteration and the data, the parent controls the look.

HTML
<!-- ItemList.vue (read-only) -->
<script setup>
defineProps({ items: Array })
</script>

<template>
  <ul>
    <li v-for="(item, index) in items" :key="item.id">
      <slot :item="item" :index="index">{{ item.name }}</slot>
    </li>
  </ul>
</template>
A scoped slot for custom rows

Two details are worth remembering. First, when a component has only a default slot, you can put v-slot directly on the component tag (<ItemList v-slot="{ item }">) and skip the <template>. Second, named scoped slots work the same way: <template #row="{ item }">. Note that name is reserved, so you cannot pass a slot prop called name and read it back.

Renderless components

If a component's only job is to hold logic and expose it through a scoped slot, it can render no HTML of its own. Such a renderless component keeps state (here an on/off flag) and lets each parent choose the markup. It is written with a render function, which you will meet in Render Functions and JSX: setup() returns a function that calls slots.default() with the data to expose.

A renderless toggle with two looks

The same behaviour now powers a disclosure button and a switch. Today most teams extract such logic into a composable instead, because a composable needs no extra component in the tree. Renderless components still make sense when the logic is tied to the template structure or needs lifecycle hooks of its own.

When to use a slot and when to use a prop

  • Use a prop for plain data and simple choices (a title string, a size, a boolean).
  • Use a slot when the parent should control the markup, or when the content is itself made of components.
  • Use a scoped slot when the child owns the data or the loop but the parent owns the appearance.
  • Prefer slots over many "render this HTML" props: a v-html prop is both awkward and unsafe.

There is more on this trade-off in Designing Components.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A child component contains <slot>Loading...</slot>. When does 'Loading...' appear?

    Content between the slot tags is fallback content. Vue renders it only if the parent provides nothing for that outlet.
  2. 2. Which syntax fills a slot named footer from the parent?

    #footer is the shorthand for v-slot:footer. It must be used on a <template> (or directly on the component when only the default slot is used).
  3. 3. In slot content written by the parent, which data can you use without a scoped slot?

    Slot content belongs to the parent template, so it sees the parent's state. To use values from the child, the child must pass them as slot props.
  4. 4. What is a scoped slot, in one sentence?

    The child binds attributes on <slot>, and the parent receives them with v-slot="{ ... }". The parent supplies the markup, the child supplies the data.

Summary

  • <slot> marks where the parent's content goes; the text inside it is fallback content.
  • Named slots use <slot name="x"> in the child and <template #x> in the parent; unwrapped content fills the default slot.
  • $slots (or useSlots()) tells a component which slots were provided, so it can skip empty wrappers.
  • #[expression] chooses the slot name dynamically.
  • Slot content is compiled in the parent's scope; scoped slots pass child data to it as slot props.
  • A renderless component keeps logic and state and renders only what its slot returns; composables are often a lighter alternative.

Next, see how classes and other attributes travel through a component in Fallthrough Attributes.