Teleport in Vue: What It Is and How to Use It

Teleport in Vue is a built-in component that lets you render part of your component's template somewhere else in the DOM, outside its normal parent. It helps move UI elements like modals or tooltips to a different place without breaking the component structure.

How It Works

Imagine you have a popup window inside a box, but you want the popup to appear outside the box so it doesn't get cut off or hidden. Teleport works like a magic door that moves that popup to another place in the house while keeping it connected to the box.

In Vue, components usually render inside their parent elements. But sometimes, UI parts like modals or dropdowns need to appear elsewhere in the page for better display or layering. Teleport lets you specify a target element in the DOM where the content should be rendered, even if it's outside the current component's tree.

This keeps your code organized and your UI working smoothly without messy hacks.

Example

This example shows a modal dialog rendered using Teleport to the #modals div outside the main app container.

vue

<template>
  <div>
    <button @click="show = true">Open Modal</button>
    <teleport to="#modals">
      <div v-if="show" class="modal">
        <p>This modal is teleported outside the main app div.</p>
        <button @click="show = false">Close</button>
      </div>
    </teleport>
  </div>
</template>

<script setup>
import { ref } from 'vue'
const show = ref(false)
</script>

<style>
.modal {
  position: fixed;
  top: 20vh;
  left: 50%;
  transform: translateX(-50%);
  background: white;
  padding: 1rem 2rem;
  box-shadow: 0 2px 8px rgba(0,0,0,0.3);
  border-radius: 8px;
  z-index: 1000;
}
</style>

Output

A button labeled 'Open Modal' inside the app. When clicked, a white modal box appears centered on the screen outside the app container with text and a 'Close' button.

When to Use

Use Teleport when you need to render UI elements outside their normal parent container for better layout or layering. Common cases include:

• Modals and dialogs that should appear above all content
• Tooltips or dropdown menus that might be clipped by parent containers
• Notifications or popups that need to be placed at the root of the document

This helps avoid CSS overflow or z-index issues and keeps your component code clean and maintainable.

Key Points

• Teleport moves content to a different DOM node without breaking Vue reactivity.
• You specify the target with the to prop using a CSS selector.
• It is useful for UI elements that need to escape parent container constraints.
• Works seamlessly with Vue's reactive system and event handling.

Key Takeaways

Teleport lets you render parts of a component outside its parent in the DOM.

It is ideal for modals, tooltips, and dropdowns that need special positioning.

You specify the destination element with the to attribute.

Teleport keeps Vue's reactivity and event handling intact.

Using Teleport helps avoid layout and layering problems.