Using Teleport in Vue.js 3: Concepts and Practical Examples

With the release of Vue.js 3, a new feature called Teleport was added, allowing developers to render a component’s content in any location of the HTML document. This makes it easy to create modals, dialogs, notifications, dropdowns, and other pop‑up UI elements without worrying about layout or stacking context.

Basic concepts

Teleport : the mechanism that moves content from its source to a target.

Source : the original location of the component’s markup.

Target : the destination element where the content will be rendered (e.g., body ).

Teleport Element : the element created inside the target.

Teleport Destination : a special component that defines the target.

Teleport Props : properties that can be passed to the teleport target.

Example 1 – Modal

The following component defines a modal that is teleported to body . The modal markup is placed inside a div.modal-mask element.

<code><span><span>&lt;<span>template</span>&gt;</span></span>
<span>  <span>&lt;<span>div</span>&gt;</span></span>
<span>    <span>&lt;<span>teleport</span> <span>to</span>=<span>"body"</span>&gt;</span></span>
<span>      <span>&lt;<span>div</span> <span>class</span>=<span>"modal-mask"</span>&gt;</span></span>
<span>        <span>&lt;<span>div</span> <span>class</span>=<span>"modal-wrapper"</span>&gt;</span></span>
<span>          <span>&lt;<span>div</span> <span>class</span>=<span>"modal-container"</span>&gt;</span></span>
<span>            <span>&lt;<span>div</span> <span>class</span>=<span>"modal-header"&gt;</span></span>
<span>              <span>&lt;<span>h3</span>&gt;</span>{{ header }}<span>&lt;/<span>h3</span>&gt;</span></span>
<span>              <span>&lt;<span>button</span> @<span>click</span>=<span>"$emit('close')"</span>&gt;</span>X<span>&lt;/<span>button</span>&gt;</span></span>
<span>            <span>&lt;/<span>div</span>&gt;</span></span>
<span>            <span>&lt;<span>div</span> <span>class</span>=<span>"modal-body"&gt;</span></span>
<span>              <span>&lt;<span>slot</span>&gt;</span>&lt;/<span>slot</span>&gt;</span></span>
<span>            <span>&lt;/<span>div</span>&gt;</span></span>
<span>            <span>&lt;<span>div</span> <span>class</span>=<span>"modal-footer"&gt;</span></span>
<span>              <span>&lt;<span>button</span> @<span>click</span>=<span>"$emit('close')"</span>&gt;</span>Close<span>&lt;/<span>button</span>&gt;</span></span>
<span>            <span>&lt;/<span>div</span>&gt;</span></span>
<span>          <span>&lt;/<span>div</span>&gt;</span></span>
<span>        <span>&lt;/<span>div</span>&gt;</span></span>
<span>      <span>&lt;/<span>div</span>&gt;</span></span>
<span>    <span>&lt;/<span>teleport</span>&gt;</span></span>
<span>  <span>&lt;/<span>div</span>&gt;</span></span>
<span>&lt;/<span>template</span>&gt;</span></span></code>

The parent component can open the modal by toggling modalOpen and passing a header prop.

<code><span><span>&lt;<span>template</span>&gt;</span></span>
<span>  <span>&lt;<span>div</span>&gt;</span></span>
<span>    <span>&lt;<span>button</span> @<span>click</span>=<span>"modalOpen = true"</span>&gt;</span>Open Modal<span>&lt;/<span>button</span>&gt;</span></span>
<span>    <span>&lt;<span>modal</span> <span>:header</span>=<span>"'My Modal'"</span> <span>v-model:show</span>=<span>"modalOpen"</span>&gt;</span></span>
<span>      <span>&lt;<span>p</span>&gt;</span>Modal content<span>&lt;/<span>p</span>&gt;</span></span>
<span>    <span>&lt;/<span>modal</span>&gt;</span></span>
<span>  <span>&lt;/<span>div</span>&gt;</span></span>
<span>&lt;/<span>template</span>&gt;</span></span>
<span>&lt;<span>script</span>&gt;</span>
<span>import Modal from './Modal.vue'</span>
<span>export default {</span>
<span>  components: { Modal },</span>
<span>  data() { return { modalOpen: false } }</span>
<span>}</span>
<span>&lt;/<span>script</span>&gt;</span></code>

Example 2 – Notifications

This example shows how to teleport a list of notification cards to body , rendering each item from a notifications array.

<code><span><span>&lt;<span>template</span>&gt;</span></span>
<span>  <span>&lt;<span>div</span>&gt;</span></span>
<span>    <span>&lt;<span>teleport</span> <span>to</span>=<span>"body"</span> <span>v-if</span>=<span>"show"</span>&gt;</span></span>
<span>      <span>&lt;<span>div</span> v-for="item in notifications" :key="item.id" class="notification" :class="item.type"&gt;</span></span>
<span>        <span>&lt;<span>span</span> class="notification-title"&gt;</span>{{ item.title }}<span>&lt;/<span>span</span>&gt;</span></span>
<span>        <span>&lt;<span>p</span>&gt;</span>{{ item.content }}<span>&lt;/<span>p</span>&gt;</span></span>
<span>      <span>&lt;/<span>div</span>&gt;</span></span>
<span>    <span>&lt;/<span>teleport</span>&gt;</span></span>
<span>  <span>&lt;/<span>div</span>&gt;</span></span>
<span>&lt;/<span>template</span>&gt;</span></span>
<span>&lt;<span>script</span>&gt;</span>
<span>export default {</span>
<span>  props: {</span>
<span>    show: { type: Boolean, default: false },</span>
<span>    notifications: { type: Array, default: () => [] }</span>
<span>  }</span>
<span>}</span>
<span>&lt;/<span>script</span>&gt;</span></code>

The parent component toggles showNotifications and supplies an array of notification objects.

<code><span><span>&lt;<span>template</span>&gt;</span></span>
<span>  <span>&lt;<span>div</span>&gt;</span></span>
<span>    <span>&lt;<span>button</span> @<span>click</span>=<span>"showNotifications = !showNotifications"</span>&gt;</span>{{ showNotifications ? 'Close Notifications' : 'Open Notifications' }}<span>&lt;/<span>button</span>&gt;</span></span>
<span>    <span>&lt;<span>notifications</span> :show="showNotifications" :notifications="notifications" /&gt;</span></span>
<span>  <span>&lt;/<span>div</span>&gt;</span></span>
<span>&lt;/<span>template</span>&gt;</span></span>
<span>&lt;<span>script</span>&gt;</span>
<span>import Notifications from './Notifications.vue'</span>
<span>export default {</span>
<span>  components: { Notifications },</span>
<span>  data() { return {</span>
<span>    showNotifications: false,</span>
<span>    notifications: [</span>
<span>      { id: 1, type: 'success', title: 'Success', content: 'Your task has been completed successfully.' },</span>
<span>      { id: 2, type: 'error', title: 'Error', content: 'An error occurred while performing your task.' }</span>
<span>    ]</span>
<span>  } }</span>
<span>}</span>
<span>&lt;/<span>script</span>&gt;</span></code>

Conclusion

Using Teleport in Vue.js 3 simplifies the management of pop‑up UI components, improves layout control, and enhances maintainability. The examples demonstrate how to create modals and notification panels that are rendered outside the normal component hierarchy, showcasing the flexibility and extensibility introduced by this new feature.