Slots: programmatic usage improvements

[Akryum]

• Start Date: 2022-06-27
• Target Major Version: 3.x
• Reference Issues: -
• Implementation PR: -

Summary

• Introduce an helper to make detecting slots with empty content easier
• Allow rendering arrays of vnodes in the template directly
• (?) Allow referencing computed properties as template tags when not using <script setup>

Basic example

<script setup>
import { computed, useSlots, getFilledSlot } from 'vue'

const slots = useSlots()
// Array of vnodes or null if empty
const FooSlot = computed(() => getFilledSlot(slots?.foo({ someProp: 'hello' })))
</script>

<template>
  <!-- Check if FooSlot is null (empty slot) -->
  <div v-if="FooSlot" class="some-padding">
    <!-- Render array of vnodes -->
    <FooSlot />
  </div>
</template>

Motivation

It's currently cumbersome and non idiomatic to check if a slot is empty to conditionally render parts of the template. For example, consider this modal component:

<template>
  <modal>
    <div class="modal-header">
      <slot name="header" />
    </div>
    <slot />
  </modal>
</template>

We probably don't want to render the .modal-header element when the user of the component doesn't put content in the header slot.

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

Vue currently only populates the header function on $slots if it is used in the template.

<template>
  <MyModal>
    Content
  </MyModal>
</template>

// Result:
console.log(this.$slots)
{}

<template>
  <MyModal>
    <template #header>
      Title
    </template>
    Content
  </MyModal>
</template>

// Result:
console.log(this.$slots)
{
  header: () => [ /* array of vnodes */ ]
}

But this falls apart as soon as you have some conditionals:

<template>
  <MyModal>
    <template #header>
      <span v-if="someCondition">Title</span>
      <span v-else-if="someOtherCondition">Title 2</span>
    </template>
    Content
  </MyModal>
</template>

$slots.header is still populated with the slot render function:

// Result:
console.log(this.$slots)
{
  header: () => [ /* array of vnodes */ ]
}

So we need to programmatically "render" the slot to check if it's really empty by calling the function:

const slots = useSlots()
const HeaderSlot = computed(() => slots.header?.())

This also allows us to check for emptiness in case we pass some props to the slot:

<template>
  <MyModal>
    <template #header="{ title }">
      <span v-if="title.startsWith('a')">Title</span>
      <span v-else-if="title.startsWith('b')">Title 2</span>
    </template>
    Content
  </MyModal>
</template>

// MyModal
const title = ref('a')
const slots = useSlots()
const HeaderSlot = computed(() => slots.header?.({ title: title.value }))

We could then check for the length of the vnodes array:

<template>
  <modal>
    <div v-if="HeaderSlot.length" class="modal-header">
      <slot name="header" title="title" />
    </div>
    <slot />
  </modal>
</template>

There are two remaining problems here:

1. The HeaderSlot array of vnodes could contain only "invalid" vnodes such as comments or empty fragments.
2. We unnecessarily call the slot function again in the template with <slot/> and we need to duplicate the slot props.

Fixing problem 1 requires using an internal function called ensureValidVNode to check is the array of vnodes contains other vnodes than comments and empty fragments.

That way we can check if the result is null, meaning empty:

<template>
  <modal>
    <div v-if="HeaderSlot" class="modal-header">
      <slot name="header" title="title" />
    </div>
    <slot />
  </modal>
</template>

Fixing problem 2 requires directly using in the template the result we have in the script. The most literal way would be to loop over the vnodes:

<template>
  <modal>
    <div v-if="HeaderSlot" class="modal-header">
      <component v-for="(s, i) in HeaderSlot" :key="i" :is="s" />
    </div>
    <slot />
  </modal>
</template>

But it's pretty unreadable and not user-friendly. A probably better alternative is using an intermediate functional component that renders the array of vnodes:

<script setup>
// ...
const RenderSlot = ({ slot }) => slot
</script>

<template>
  <modal>
    <div v-if="HeaderSlot" class="modal-header">
      <RenderSlot :slot="HeaderSlot" />
    </div>
    <slot />
  </modal>
</template>

You can find a working example here with all API styles (Options API, Composition API, script setup).

A big developer experience improvement could still be made for problem 2, by directly being able to render an array of vnodes in a template, thus removing the need for an intermediate component:

<template>
  <modal>
    <div v-if="HeaderSlot" class="modal-header">
      <HeaderSlot /> <!-- Tag? -->
    </div>
    <slot />
  </modal>
</template>

Note: I like the tag syntax but it implies being able to put attributes on it which wouldn't work. Maybe the compiler can raise warnings about this?

Detailed design

getFilledSlot is a function that takes an array of vnodes and returns it if it's not empty (i.e. contains valid vnodes), null otherwise to facilitate conditionals.
It could be implemented like this:

export function getFilledSlot (vnodes: VNodeArrayChildren | null) {
  return vnodes ? ensureValidVNode(vnodes) : null
}

Usage:

const SomeSlot = computed(() => getFilledSlot(slots.some?.({ prop: 'hello' })))
const isSomeSlotFilled = computed(() => SomeSlot.value != null)

Note: the returned result from the slot function can be null hence the additional conditional in getFilledSlot.

---

Allow putting a variable containing an array of vnodes to be used as template tag:

<template>
  <!-- Array of vnodes from the slot -->
  <SomeSlot />
</template>

Usage in Option API could be improved if we could resolve template tag using the computed properties:

<script>
export default {
  computed: {
    HeaderSlot () {
      return getFilledSlot(this.$slots.header?.({ title: this.title }))
    }
  }
}
<script>

<template>
  <HeaderSlot />
</template>

Drawbacks

getFilledSlot: This could be implemented in user space but with hacky solutions involving copying an internal function.

Adoption strategy

This is an additive API.

Unresolved questions

• Naming of getFilledSlot?
• Choose a solution to render vnodes in a template?

[stafyniaksacha]

This would be really helpful.
About the name, maybe resolveSlot?

Note, this would be also really useful to have a signature with a string as first parameter, for the slot name, and slot parameters optional second argument

getFilledSlot (slot: string, slotProps: any) 
getFilledSlot (vnodes: VNodeArrayChildren | null)

[Akryum]

The userland implementation I shared has an issue
In some cases the vnodes array isn't properly updated. :(

[Akryum]

Looks like it's an issue in core: vuejs/core#6202

[sylvainpolletvillard]

Detecting slots with empty content is one thing, but I think the need goes beyond that. I recently ran into a problem where my template had to adapt according to the number of elements contained in my slot. Filtering the VNodes was quite cumbersome as you explain, especially if you are not familiar with the VNode API, so instead I solved my issue with a watcher and DOM queries. But if felt wrong and definitely non-intuitive.

May I suggest getFilledSlot to return the rendered Nodes instead of the VNodes ? This would make easier to write computed based on various conditions on slot content, and not only if it's empty or not.

[thedamon]

This is a good point. DOM queries won't work with SSR either so can introduce jank. It would be nice to be able to interrogate the number of "real" children in a slot (though when one child is a component this becomes convoluted, but that may be acceptable)

[Akryum]

Other proposal: update useSlots().foo() to return a falsy value if there are no valid vnodes (it's "empty")?
Would be a breaking change though

[Akryum]

Or maybe a new composable useFilledSlots() or useValidSlots()?

<script setup>
import { useValidSlots, computed } from 'vue'

const slots = useValidSlots()
const TitleSlot = computed(() => slots.title?.())
</script>

<template>
  <div v-if="TitleSlot" style="padding: 12px;">
    <TitleSlot />
  </div>
</template>

[domnantas]

useSlots().foo() returning null when there are no valid vnodes seems like the most intuitive approach. Similar to how Vue 2 handles empty slots.

Disagree on the additional composable, it would cause confusion when to use useSlots and useValidSlots

[thedamon]

I agree that the ideal usecase is a vnode tree per slot that excludes 'empty' vnodes. I agree that the "best" solution is to change how useSlots works.. however it's true that would be a breaking change and could cause bugs. (maybe much more likely to fix bugs because i think most times you check for slots.slotName truthiness you expect it to be false when it's empty and in Vue 2 that was more likely the case, but it would change behaviour nonetheless).

I feel though, that the return without the empty vnodes would be much more useful overall. And maybe more useful anytime you're working with vnodes, not just with slot content.

[posva]

Worth adding as a reference issue:

• Request to add an official way to check if slot is empty core#4733

[posva]

Another idea of API could be one that only requires changes to the template instead of having to rely on useSlots() in the <script>:

<template>
  <!-- renders only if slot is not empty -->
  <slot-filtered name="foo" v-bind="stuff">
    <div class="wrapper">
      <!-- automatically inherits everything from the <slot-filtered> parent -->
      <slot></slot>
    </div>
  </slot-filtered>
</template>

This would generate a different compiled code than the existing one that also renders the slot just once (maybe a renderSlotWithContent() function) and is tree-shakeable.

Everything goes on the slot-filtered instead of going on slot. If the slot has no content (based on the internal ensureValidVNode() function), it will skip rendering te div.wrapper element, otherwise render the slot content as children of the div

[Akryum]

Or we could keep <slot> and have a way to decide where to put the slot content:

<template>
  <slot name="description" v-bind="props">
    <div class="padding">
      <slot-content />
    </div>
    
    <template #fallback>
      Default content
    </template>
  </slot>
</template>

[posva]

yes! Maybe having the content within <slot> makes more sense from the compiler perspective

[thedamon]

Oh this is interesting. it solves the essential problem without mucking around with new functions and APIs and just relies on the already existent show 'default' behaviour. I do worry a little because the variety of options for declaring slots in a template is already a bit difficult to reason about.

[thedamon]

Strange and different idea to solve the problem:

An app.config setting to automatically filter out empty vnodes from the return of things like useSlots and children when called in component code.

I think most developers intuitively assume that vnodes.length = 1 means there is content in there, and the logic that Vue itself uses to decide whether to display default slot content could be considered the official method of determining that. That could also be a way of making a 'breaking' change much easier to introduce as the old behaviour would be a simple toggle.

The idea of modifying useSlots is nice because it elegantly makes what often is confusing go away without needing to think about the difference and decide whether to use an obscure utility function to get the behaviour that seems like what it should actually be.

Scrapping all that, another way that might be the easiest to introduce, would be exporting ensureValidVNode from vue (or maybe a pluralized version, or option that takes an Array). I dislike the term 'valid' outside of the usecase in vue itself, but it is difficult to decide on the right terminology here. As a utility function it probably could be used a lot in userland, even as a best practice where it wouldn't be today.

If I were to solve this in my own codebase today I'd make a composable called useSlotContent(slotName) and have it return slot content with "invalid" vnodes filtered out, but null rather than an empty array if there are none left to allow simple Boolean checks. That solves @sylvainpolletvillard's issue about wanting to check length of slot content. (again the idea of an 'alternate' useValidSlots solves this similarly, but in general an additional method that's basically the same as an existing one does seem unfortunate)

[Tofandel]

A config option would make it a nightmare for libraries because you can't assume the value of the config

[MLMdlb]

Is this rfc still in discussion ? Feels like not being able to catch an empty slot is an issue.