From cb8ba12191f00b142ba63fbcda0dddfd9027a9a7 Mon Sep 17 00:00:00 2001
From: skirtle <65301168+skirtles-code@users.noreply.github.com>
Date: Sat, 7 Jan 2023 07:05:33 +0000
Subject: [PATCH] Add an API entry for `<template>`

---
 src/api/built-in-special-elements.md | 25 ++++++++++++++++++++++++-
 1 file changed, 24 insertions(+), 1 deletion(-)

diff --git a/src/api/built-in-special-elements.md b/src/api/built-in-special-elements.md
index 1eb8a565a1..ce72316a47 100644
--- a/src/api/built-in-special-elements.md
+++ b/src/api/built-in-special-elements.md
@@ -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}
@@ -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)