diff --git a/src/api/built-in-components.md b/src/api/built-in-components.md index 8f79c04d04..62e75b394f 100644 --- a/src/api/built-in-components.md +++ b/src/api/built-in-components.md @@ -1,5 +1,21 @@ # Built-In Components +Built-in components can be used directly in templates without needing to be registered. + +The ``, ``, ``, and `` components can all be tree-shaken by bundlers, so that they are only included in the build if they're used. They can also be imported explicitly if you need direct access to the component itself: + +```js +// CDN build of Vue +const { KeepAlive, Teleport, Transition, TransitionGroup } = Vue +``` + +```js +// ESM build of Vue +import { KeepAlive, Teleport, Transition, TransitionGroup } from 'vue' +``` + +`` and `` are component-like features of template syntax. They are not true components and they can't be imported like the components shown above. + ## component - **Props:** @@ -10,8 +26,6 @@ A "meta component" for rendering dynamic components. The actual component to render is determined by the `is` prop. An `is` prop as a string could be either an HTML tag name or a Component name. -- **Example:** - ```html @@ -27,6 +41,27 @@ ``` + 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: + + ```js + const { Transition, TransitionGroup } = Vue + + const Component = { + components: { + Transition, + TransitionGroup + }, + + template: ` + + ... + + ` + } + ``` + + Registration is not required if you pass the component itself to `is` rather than its name. + - **See also:** [Dynamic Components](../guide/component-dynamic-async.html) ## transition diff --git a/src/guide/render-function.md b/src/guide/render-function.md index adfd00b9e8..a5a17a7689 100644 --- a/src/guide/render-function.md +++ b/src/guide/render-function.md @@ -551,6 +551,22 @@ render () { [`resolveDirective`](/api/global-api.html#resolvedirective) is the same function that templates use internally to resolve directives by name. That is only necessary if you don't already have direct access to the directive's definition object. +### Built-in Components + +[Built-in components](/api/built-in-components.html) such as ``, ``, ``, and `` are not registered globally by default. This allows bundlers to perform tree-shaking, so that the components are only included in the build if they are used. However, that also means we can't access them using `resolveComponent` or `resolveDynamicComponent`. + +Templates have special handling for those components, automatically importing them when they are used. When we're writing our own `render` functions, we need to import them ourselves: + +```js +const { h, KeepAlive, Teleport, Transition, TransitionGroup } = Vue + +// ... + +render () { + return h(Transition, { mode: 'out-in' }, /* ... */) +} +``` + ## JSX If we're writing a lot of `render` functions, it might feel painful to write something like this: