Skip to content

Commit 563ed27

Browse files
docs: expand the explanation about using VNodes with <component> (#1310)
1 parent 5ddaf35 commit 563ed27

File tree

1 file changed

+10
-8
lines changed

1 file changed

+10
-8
lines changed

src/api/built-in-components.md

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ import { KeepAlive, Teleport, Transition, TransitionGroup } from 'vue'
2020

2121
- **Props:**
2222

23-
- `is` - `string | Component`
23+
- `is` - `string | Component | VNode`
2424

2525
- **Usage:**
2626

@@ -41,6 +41,8 @@ import { KeepAlive, Teleport, Transition, TransitionGroup } from 'vue'
4141
<component :is="href ? 'a' : 'span'"></component>
4242
```
4343

44+
- **Usage with built-in components:**
45+
4446
The built-in components `KeepAlive`, `Transition`, `TransitionGroup`, and `Teleport` can all be passed to `is`, but you must register them if you want to pass them by name. For example:
4547

4648
```js
@@ -62,15 +64,15 @@ import { KeepAlive, Teleport, Transition, TransitionGroup } from 'vue'
6264

6365
Registration is not required if you pass the component itself to `is` rather than its name.
6466

65-
- **key:**
67+
- **Usage with VNodes:**
6668

67-
When using <component :is="vnode"> and passing vnode of the same type, you need to provide keys:
68-
69-
```html
70-
<component :is="current" :key="selected" />
71-
```
69+
In advanced use cases, it can sometimes be useful to render an existing VNode via a template. Using a `<component>` makes this possible, but it should be seen as an escape hatch, used to avoid rewriting the entire template as a `render` function.
70+
71+
```html
72+
<component :is="vnode" :key="aSuitableKey" />
73+
```
7274

73-
Otherwise, you are passing two compiled vnodes of the same type to the renderer. Because they are compiled as completely static, they will not be updated at all.
75+
A caveat of mixing VNodes and templates in this way is that you need to provide a suitable `key` attribute. The VNode will be considered static, so any updates will be ignored unless the `key` changes. The `key` can be on the VNode or the `<component>` tag, but either way it must change every time you want the VNode to re-render. This caveat doesn't apply if the nodes have different types, e.g. changing a `span` to a `div`.
7476

7577
- **See also:** [Dynamic Components](../guide/component-dynamic-async.html)
7678

0 commit comments

Comments
 (0)