All You Need to Know About Teleport in Vue 3

Vue 3's Teleport allows you to move component templates to different parts of the DOM while preserving their Vue context and reactivity, enabling more flexible and powerful UI rendering across your application.

5 min read

December 2nd, 2024

Nick Mousavi

What is Vue Teleport ?

Teleport is a powerful Vue 3 feature that allows you to move a component's template to a different location in the DOM tree while preserving its vue context and reactivity.

It solves common challenges like rendering

modals

tooltips

, or

overlays

that need to break out of the current component's styling or layout constraints.

When a parent component has

overflow: hidden

or specific layout constraints, rendering a

Modal

becomes challenging. Teleport solves this by allowing you to move (render) your

Modal

to a different location in the DOM, ensuring it displays correctly regardless of parent component styling.

How to use Vue Teleport ?

Here is the simplest way possible to use Teleport in Vue 3.

<template>
<Teleport to="body">   <div> My Element </div>
</Teleport>
</template>

Now if you check your

body

tag in the browser, you can find

<div> My Element </div>

Actually Vue 3 Teleported our element to

body

tag.

<body>
  <div> My Element </div>
</body>

The
to
prop in Teleport allows you to specify the target element for rendering, accepting either a CSS selector or a direct DOM node reference.

But the target(

) should be an element that already mounted and exit in the DOM. Otherwise you should use defer

Logical vs Visual Hierarchy

only affects the rendered DOM structure, not the logical component hierarchy. Teleported components retain their parent-child relationships,

So if you used props, events, and dependency injection, they continue to function as expected.🤠

<template>
  <div class="parent-component">
    <Teleport to="body">
      <child-component :message="parentMessage" @some-event="handleChildEvent"/>
    </Teleport>
  </div>
</template>

<script setup>
import ChildComponent from './ChildComponent.vue'

const parentMessage = ref('My prop for child')

const handleChildEvent = (data) => console.log('event from child', data)
</script>

Target Order in Vue Teleport

Based on Vue official doc, several

components can target the same DOM element. Content is appended in the order the teleports are mounted.

ComponentA

is mounted before

componentB

and both teleported to

body

, therefore the structure will be like this:

<body>
  <ComponentA/>
  <ComponentB/>
</body>

Defer

defer

is a new prop that you can use from Vue 3.5 an above, it allow us to target to element that appear after our

Teleport

in the component tree, ensuring the target is available before teleporting.

When

defer

is set to

true

, the teleported content waits for the initial render to complete before being mounted to its target location.

How to Disable the Teleport

The

disabled

prop in Vue's Teleport doesn't remove the

Teleport

component itself

Instead, it changes how the content is rendered. When

disabled

true

, the teleported content simply renders in its original component location, maintaining all of its existing component context and behavior.

<template>
<Teleport to="body" :disabled="isDisabled">
  <!-- Teleport Content -->
</Teleport>
</template>

We can conditionally teleport our component to other location or keep it on its location.

Conclusion

is a powerful addition to Vue 3, simplifying the management of UI elements that require specific DOM positioning while maintaining a logical component structure.

10 Questions and Answers Teleport in Vue 3

Teleport is a built-in component that allows you to render a part of a component's template at a different location in the DOM, while maintaining its original Vue component context and reactivity.

<teleport to="body">
  <div>This content will be rendered in the body tag</div>
</teleport>

Yes, Teleported components maintain their full logical hierarchy, meaning they can still receive props, emit events, and use dependency injection just like they would in their original location.

disabled

prop in Teleport?

The

disabled

prop allows you to conditionally render teleported content in its original component location instead of the specified target. When set to

true

, the content renders where the Teleport component is originally placed.

and
disabled
props in Teleport?

to
specifies the target location for rendering (can be a CSS selector or DOM node)
disabled
determines whether the content should be teleported or rendered in its original location, providing a dynamic rendering strategy

Vue Teleport is a built-in component in Vue 3, providing native support for the portal functionality. In contrast, portal-vue was a third-party plugin used in Vue 2 to achieve similar results. Vue Teleport simplifies the implementation and eliminates the need for external dependencies.

When multiple

components target the same DOM element, their content is appended in the order they are mounted. The later mounts appear after earlier ones within the target.

While teleporting outside the Vue app is common, you can teleport within the app. However, the target element must already exist in the DOM when the

component mounts. This may require conditional rendering or using the defer prop introduced in Vue 3.5 to delay target resolving.

React

Portal

and Vue

Teleport

are both solutions for rendering child components outside of their current DOM hierarchy, which is particularly useful for creating modals, tooltips, and other overlay components. They solve the common issue of component styling and z-index limitations by allowing developers to render content at a different location in the DOM tree while maintaining the original component's React or Vue context.

The key similarity is their core purpose: to break free from the typical component nesting constraints and render components in a different part of the DOM. This is crucial for creating UI elements that need to overlay other content or escape potential styling or positioning restrictions.

// React Portal Example
import React from 'react';
import ReactDOM from 'react-dom';

function ReactModalExample() {
  return ReactDOM.createPortal(
    <div className="modal">
      <h2>React Portal Modal</h2>
      <p>This modal is rendered outside the current DOM hierarchy</p>
    </div>,
    document.body // Renders directly to the body
  );
}

React