1---
2title: Teleport Component Best Practices
3impact: MEDIUM
4impactDescription: Teleport renders content outside the component's DOM position, which is essential for overlays but affects styling and layout
5type: best-practice
6tags: [vue3, teleport, modal, overlay, positioning, responsive]
7---
8 
9# Teleport Component Best Practices
10 
11**Impact: MEDIUM** - `<Teleport>` renders part of a component's template in a different place in the DOM while preserving the Vue component hierarchy. Use it for overlays (modals, toasts, tooltips) or any UI that must escape stacking contexts, overflow, or fixed positioning constraints.
12 
13## Task List
14 
15- Teleport overlays to `body` or a dedicated container outside the app root
16- Keep a shared target for similar UI (`#modals`, `#notifications`) and control layering with order or z-index
17- Use `:disabled` for responsive layouts that should render inline on small screens
18- Remember props, emits, and provide/inject still work through teleport
19- Avoid relying on parent stacking contexts or transforms for teleported UI
20 
21## Teleport Overlays Out of Transformed Containers
22 
23When an ancestor has `transform`, `filter`, or `perspective`, fixed-position overlays can behave like they are locally positioned. Teleport escapes that context.
24 
25**BAD:**
26```vue
27<template>
28  <div class="animated-container">
29    <button @click="open = true">Open</button>
30 
31    <!-- Broken: fixed positioning is scoped to the transformed parent -->
32    <div v-if="open" class="modal">Modal</div>
33  </div>
34</template>
35 
36<style>
37.animated-container {
38  transform: translateZ(0);
39}
40 
41.modal {
42  position: fixed;
43  inset: 0;
44  z-index: 9999;
45}
46</style>
47```
48 
49**GOOD:**
50```vue
51<template>
52  <div class="animated-container">
53    <button @click="open = true">Open</button>
54 
55    <Teleport to="body">
56      <div v-if="open" class="modal">Modal</div>
57    </Teleport>
58  </div>
59</template>
60```
61 
62## Responsive Layouts with `disabled`
63 
64Use `:disabled` to render inline on mobile and teleport on larger screens:
65 
66```vue
67<script setup>
68import { useMediaQuery } from '@vueuse/core'
69 
70const isMobile = useMediaQuery('(max-width: 768px)')
71</script>
72 
73<template>
74  <Teleport to="body" :disabled="isMobile">
75    <nav class="sidebar">Navigation</nav>
76  </Teleport>
77</template>
78```
79 
80## Logical Hierarchy Is Preserved
81 
82Teleport changes DOM position, not the Vue component tree. Props, emits, slots, and provide/inject still work:
83 
84```vue
85<template>
86  <Teleport to="body">
87    <ChildPanel :message="message" @close="open = false" />
88  </Teleport>
89</template>
90```
91 
92## Multiple Teleports to the Same Target
93 
94Teleports to the same target append in declaration order:
95 
96```vue
97<template>
98  <Teleport to="#notifications">
99    <div>First</div>
100  </Teleport>
101 
102  <Teleport to="#notifications">
103    <div>Second</div>
104  </Teleport>
105</template>
106```
107 
108Use a shared container to keep stacking predictable, and apply z-index only when you need explicit layering.
109