Skip to content

Using named slots directly on the component #2190

Open

Description

@skirtles-code

There are a few places in the docs where we imply or state that you can only use v-slot directly on the component tag for the default slot. So, for example, this isn't allowed:

<MyComponent #header>
  Header content
</MyComponent>

Following the docs, this should be written using a <template> tag instead:

<MyComponent>
  <template #header>
    Header content
  </template>
</MyComponent>

But, in practice, this first example does seem to work.

I'm unclear whether this is intentional or not.


The Vue 2 docs are really explicit about this, https://v2.vuejs.org/v2/guide/components-slots.html:

Note that v-slot can only be added to a <template> (with one exception), unlike the deprecated slot attribute.

The Vue 3 guide isn't quite so explicit, but the slots guide gives no indication that this is supported. In the API reference it copies the wording from the Vue 2 docs:

Limited to [...] components (for a lone default slot with props)

The RFC, https://github.com/vuejs/rfcs/blob/master/active-rfcs/0001-new-slot-syntax.md, doesn't tackle this directly, but it does strongly imply that only the default slot can be used this way:

v-slot can be used directly on a component, without an argument, to indicate that the component's default slot is a scoped slot

Activity

  1. ValentinYoushkevich commented on Oct 29, 2026

    @ValentinYoushkevich

    The compiler does accept this form: <MyComponent #header>…</MyComponent> compiles to the same render function as the <template #header> form in Vue 3, 2.7 and 2.6, and vuejs/core has an on component named slot test for it. Could someone from the core team confirm whether this is intentional? If it is, the guide and the API reference could mention it; if not, it may be worth calling it deprecated. This came up in vuejs/eslint-plugin-vue#3192, where vue/valid-v-slot currently reports this form.

  2. ValentinYoushkevich commented on Nov 9, 2026

    @ValentinYoushkevich

    Opened #3491 to update the docs accordingly.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions