Teleport

## The problem Teleport solves A Vue component renders its template where the component itself sits in the DOM. That is usually what you want, but a **modal** is the classic exception. Its open/close state and its trigger button belong to one component, yet visually it must cover the whole viewport. When that component lives deep inside a scrolling panel, several CSS facts work against it: - an ancestor with `overflow: hidden` or `overflow: auto` clips an absolutely positioned descendant to its box; - an ancestor with `transform`, `perspective` or `filter` becomes the containing block for `position: fixed`, so a "fixed" modal is positioned relative to that ancestor rather than the viewport; - the modal's `z-index` only competes inside its ancestors' **stacking context**, so an unrelated sibling with a higher stacking context can cover it. Moving the modal's markup up into the app root would fix the layout but scatter one feature across unrelated files. ## What `<Teleport>` does `<Teleport>` is one of the built-in components shipped in the `vue` package. It renders its slot content into a different DOM node while the content stays part of the same component: ```vue <script setup lang="ts"> import { ref } from 'vue' const open = ref(false) </script> <template> <button @click="open = true">Delete account</button> <Teleport to="body"> <div v-if="open" class="modal"> <p>Are you sure?</p> <button @click="open = false">Cancel</button> </div> </Teleport> </template> ``` The button stays inside the scrolling panel; the `.modal` element is inserted as a child of `body`. The `open` ref, the click handlers and the component's reactivity are exactly what they would be without the Teleport. ## What `to` accepts | Value of `to` | How Vue uses it | |---|---| | A CSS selector string such as `"body"`, `"#modals"`, `".layer"`, `"[data-teleport]"` | Resolved with the renderer's `querySelector`, so the **first** matching element wins | | An actual DOM element (`HTMLElement`) | Used directly as the container | The prop is required. If `to` changes while the Teleport is enabled, Vue moves the already-rendered content to the new target rather than recreating it. ## What you see in the DOM 1. In the original position, Vue leaves two placeholder nodes: in development they are the comments `<!--teleport start-->` and `<!--teleport end-->`; in production they are empty text nodes. 2. Inside the target, the teleported elements are appended. 3. When several `<Teleport>`s point at the same target, each mount **appends** after the earlier ones, so a second modal opened later ends up after the first inside `#modals` and, with equal `z-index`, paints on top of it. 4. When the owning component unmounts, Vue removes the teleported nodes from the target as well; nothing is left behind in `body`. ## Practical guidance - Prefer a dedicated container placed in `index.html` next to the app's mount element, such as `<div id="modals"></div>`, over `body` itself: the container is guaranteed to exist before the app mounts and keeps overlays grouped. - Keep the trigger and the modal in the same SFC; that locality is the whole reason to teleport instead of lifting state up. - Teleport changes only the **DOM position**. Props, emitted events and injections still flow through the component tree, and Vue Devtools still shows the modal under its parent. - Because DOM position changes, anything that depends on DOM ancestry changes too: native event bubbling, descendant CSS selectors and `contains()`-based click-outside checks now see `body`, not the panel. - Animating the teleported modal is a separate concern handled by wrapping content in `<Transition>`. ## Teleport compared with the alternatives Before `<Teleport>` existed, teams escaped nested layouts in other ways, and interviewers sometimes ask why Teleport is preferred: | Approach | What it costs | |---|---| | Render the modal in `App.vue` and drive it through shared state | The feature's markup, state and handlers are split across distant files | | Mount a second Vue app into `body` for each modal | The modal is cut off from the first app's component tree, so injections, plugins and parent listeners no longer reach it | | Move the node yourself with `appendChild` in `onMounted` | Vue no longer knows where its nodes are; patches and unmounts can misbehave | | `<Teleport to="body">` | Nothing structural: one SFC, one component tree, only the DOM position changes | The last row is the reason Teleport is the default answer: it is the only option that keeps the component relationship intact while Vue itself manages the moved nodes, including removing them on unmount. ## Summary `<Teleport>` separates **where markup is written** from **where its nodes are inserted**. The component keeps ownership of state and lifecycle; only the rendered DOM moves. That is why it is the standard Vue answer for modals, toasts and dropdowns that must escape clipping or stacking inside a nested layout.