Skip to content

Add an API entry for <template> #2154

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jan 8, 2023
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 24 additions & 1 deletion src/api/built-in-special-elements.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Built-in Special Elements {#built-in-special-elements}

:::info Not Components
`<component>` and `<slot>` are component-like features and part of the template syntax. They are not true components and are compiled away during template compilation. As such, they are conventionally written with lowercase in templates.
`<component>`, `<slot>` and `<template>` are component-like features and part of the template syntax. They are not true components and are compiled away during template compilation. As such, they are conventionally written with lowercase in templates.
:::

## `<component>` {#component}
Expand Down Expand Up @@ -139,3 +139,26 @@ Denotes slot content outlets in templates.
`<slot>` elements in Vue templates are compiled into JavaScript, so they are not to be confused with [native `<slot>` elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/slot).

- **See also:** [Component - Slots](/guide/components/slots.html)

## `<template>` {#template}

The `<template>` tag is used as a placeholder when we want to use a built-in directive without rendering an element in the DOM.

- **Details:**

The special handling for `<template>` is only triggered if it is used with one of these directives:

- `v-if`, `v-else-if`, or `v-else`
- `v-for`
- `v-slot`

If none of those directives are present then it will be rendered as a [native `<template>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/template) instead.

A `<template>` with a `v-for` can also have a [`key` attribute](/api/built-in-special-attributes.html#key). All other attributes and directives will be discarded, as they aren't meaningful without a corresponding element.

Single-file components use a [top-level `<template>` tag](/api/sfc-spec.html#language-blocks) to wrap the entire template. That usage is separate from the use of `<template>` described above. That top-level tag is not part of the template itself and doesn't support template syntax, such as directives.

- **See also:**
- [Guide - `v-if` on `<template>`](/guide/essentials/conditional.html#v-if-on-template)
- [Guide - `v-for` on `<template>`](/guide/essentials/list.html#v-for-on-template)
- [Guide - Named slots](/guide/components/slots.html#named-slots)