Slots·续

In the example below we define a Card component with three conditional slots: header, footer and the default one. When content for the header / footer / default is present, we want to wrap it to provide additional styling:

<template>
  <div class="card">
    <div v-if="$slots.header" class="card-header">
      <slot name="header" />
    </div>

    <div v-if="$slots.default" class="card-content">
      <slot />
    </div>

    <div v-if="$slots.footer" class="card-footer">
      <slot name="footer" />
    </div>
  </div>
</template>

Try it in the Playground

Dynamic Slot Names

Dynamic directive arguments also work on v-slot, allowing the definition of dynamic slot names:

<base-layout>
  <template v-slot:[dynamicSlotName]>
    ...
  </template>

<!-- with shorthand -->
  <template #[dynamicSlotName]>
    ...
  </template>
</base-layout>

Do note the expression is subject to the syntax constraints of dynamic directive arguments.

Scoped Slots

As discussed in Render Scope, slot content does not have access to state in the child component.

However, there are cases where it could be useful if a slot's content can make use of data from both the parent scope and the child scope. To achieve that, we need a way for the child to pass data to a slot when rendering it.

In fact, we can do exactly that - we can pass attributes to a slot outlet just like passing props to a component. The parent template receives slot props with v-slot, while the child template passes props to the slot outlet when rendering:

<!-- Parent template (usage) -->
<ChildComponent v-slot="receivedProps">
  {{ receivedProps.text }} {{ receivedProps.count }}
</ChildComponent>
<!-- Child template (slot definition) -->
<!-- render with props! -->
<slot
  text="hello"
  :count="1"
/>

Receiving the slot props is a bit different when using a single default slot vs. using named slots. The example above receives props using a single default slot, by using v-slot directly on the ChildComponent tag.

Diagram showing a scoped slot where the child component passes data back to the parent-provided slot content

Try it in the Playground

Try it in the Playground

The props passed to the slot by the child are available as the value of the corresponding v-slot directive, which can be accessed by expressions inside the slot.

You can think of a scoped slot as a function being passed into the child component. The child component then calls it, passing props as arguments:

ChildComponent({
  // passing the default slot, but as a function
  default: (receivedProps) => {
    return `${receivedProps.text} ${receivedProps.count}`
  }
})

function ChildComponent(slots) {
  // call the slot function with props!
  return slots.default({ text: 'hello', count: 1 })
}

In fact, this is very close to how scoped slots are compiled, and how you would use scoped slots in manual render functions.

Notice how v-slot="receivedProps" matches the slot function signature. Just like with function arguments, we can use destructuring in v-slot:

<ChildComponent v-slot="{ text, count }">
  {{ text }} {{ count }}
</ChildComponent>

Named Scoped Slots

Named scoped slots work similarly - slot props are accessible as the value of the v-slot directive: v-slot:name="receivedProps". When using the shorthand, it looks like this:

<MyComponent>
  <template #header="headerProps">
    {{ headerProps }}
  </template>

<template #default="defaultProps">
    {{ defaultProps }}
  </template>

<template #footer="footerProps">
    {{ footerProps }}
  </template>
</MyComponent>

Passing props to a named slot:

<slot name="header" message="hello" />

Note the name of a slot won't be included in the props because it is reserved - so the resulting headerProps would be { message: 'hello' }.

If you are mixing named slots with the default scoped slot, you need to use an explicit <template> tag for the default slot. Attempting to place the v-slot directive directly on the component will result in a compilation error. This is to avoid any ambiguity about the scope of the props of the default slot. For example:

<!-- <MyComponent> template -->
<div>
  <slot message="hello" />
  <slot name="footer" />
</div>
<!-- This template won't compile -->
<MyComponent v-slot="{ message }">
  <p>{{ message }}</p>
  <template #footer>
    <!-- message belongs to the default slot, and is not available here -->
    <p>{{ message }}</p>
  </template>
</MyComponent>

Using an explicit <template> tag for the default slot helps to make it clear that the message prop is not available inside the other slot:

<MyComponent>
  <!-- Use explicit default slot -->
  <template #default="{ message }">
    <p>{{ message }}</p>
  </template>

<template #footer>
    <p>Here's some contact info</p>
  </template>
</MyComponent>

Fancy List Example

You may be wondering what would be a good use case for scoped slots. Here's an example: imagine a <FancyList> component that renders a list of items - it may encapsulate the logic for loading remote data, using the data to display a list, or even advanced features like pagination or infinite scrolling. However, we want it to be flexible with how each item looks and leave the styling of each item to the parent component consuming it. So the desired usage may look like this:

<FancyList :api-url="url" :per-page="10">
  <template #item="{ body, username, likes }">
    <div class="item">
      <p>{{ body }}</p>
      <p>by {{ username }} | {{ likes }} likes</p>
    </div>
  </template>
</FancyList>

Inside <FancyList>, we can render the same <slot> multiple times with different item data (notice we are using v-bind to pass an object as slot props):

<ul>
  <li v-for="item in items">
    <slot name="item" v-bind="item" />
  </li>
</ul>

Try it in the Playground

Try it in the Playground

Renderless Components

The <FancyList> use case we discussed above encapsulates both reusable logic (data fetching, pagination etc.) and visual output, while delegating part of the visual output to the consumer component via scoped slots.

If we push this concept a bit further, we can come up with components that only encapsulate logic and do not render anything by themselves - visual output is fully delegated to the consumer component with scoped slots. We call this type of component a Renderless Component.

An example renderless component could be one that encapsulates the logic of tracking the current mouse position:

<MouseTracker v-slot="{ x, y }">
  Mouse is at: {{ x }}, {{ y }}
</MouseTracker>

Try it in the Playground

Try it in the Playground

While an interesting pattern, most of what can be achieved with Renderless Components can be achieved in a more efficient fashion with Composition API, without incurring the overhead of extra component nesting. Later, we will see how we can implement the same mouse tracking functionality as a Composable.

That said, scoped slots are still useful in cases where we need to both encapsulate logic and compose visual output, like in the <FancyList> example.



url: /guide/components/provide-inject.md