1---
2title: Handle Teleport SSR Hydration Carefully
3impact: HIGH
4impactDescription: Teleported content causes hydration mismatches in SSR/SSG applications
5type: gotcha
6tags: [vue3, teleport, ssr, nuxt, hydration]
7---
8 
9# Handle Teleport SSR Hydration Carefully
10 
11**Impact: HIGH** - Teleports require special handling during SSR. The teleported content is not part of the server-rendered HTML string, causing hydration mismatches that can break the application or cause content to disappear.
12 
13This is a critical issue for Nuxt, Quasar SSR, and custom Vue SSR setups.
14 
15## Task Checklist
16 
17- [ ] Wrap Teleport in `<ClientOnly>` component (Nuxt) for client-only rendering
18- [ ] Use conditional rendering based on mount state for non-Nuxt SSR
19- [ ] Use `data-allow-mismatch` attribute in Vue 3.5+ when intentional
20- [ ] Test SSR applications thoroughly for hydration issues
21 
22**Problem - SSR Hydration Mismatch:**
23```vue
24<template>
25  <!-- Server renders nothing for teleported content -->
26  <!-- Client expects teleported content at #modals -->
27  <!-- = Hydration mismatch -->
28  <Teleport to="#modals">
29    <div v-if="showModal" class="modal">
30      Modal content
31    </div>
32  </Teleport>
33</template>
34```
35 
36Common error messages:
37```
38[Vue warn]: Hydration children mismatch in <div>:
39server rendered element contains fewer child nodes than client vdom.
40```
41 
42**Solution 1 - Nuxt ClientOnly:**
43```vue
44<template>
45  <button @click="showModal = true">Open Modal</button>
46 
47  <!-- Only render on client, avoiding SSR -->
48  <ClientOnly>
49    <Teleport to="body">
50      <div v-if="showModal" class="modal">
51        Modal content
52      </div>
53    </Teleport>
54  </ClientOnly>
55</template>
56```
57 
58**Solution 2 - Manual Client Detection:**
59```vue
60<template>
61  <button @click="showModal = true">Open Modal</button>
62 
63  <!-- Only render after component mounts on client -->
64  <Teleport v-if="isMounted" to="body">
65    <div v-if="showModal" class="modal">
66      Modal content
67    </div>
68  </Teleport>
69</template>
70 
71<script setup>
72import { ref, onMounted } from 'vue'
73 
74const showModal = ref(false)
75const isMounted = ref(false)
76 
77onMounted(() => {
78  isMounted.value = true
79})
80</script>
81```
82 
83**Solution 3 - Vue 3.5+ data-allow-mismatch:**
84```vue
85<template>
86  <!-- Suppress hydration warnings for intentional mismatches -->
87  <div data-allow-mismatch>
88    <Teleport to="body">
89      <div v-if="showModal" class="modal">
90        Modal content
91      </div>
92    </Teleport>
93  </div>
94</template>
95```
96 
97## SSR with Multiple Teleports
98 
99Multiple teleports to the same target can cause additional hydration issues:
100 
101```vue
102<!-- Parent.vue -->
103<template>
104  <!-- First teleport -->
105  <Teleport to="#modals">
106    <NotificationBanner />
107  </Teleport>
108 
109  <ChildComponent />
110</template>
111 
112<!-- ChildComponent.vue -->
113<template>
114  <!-- Second teleport to same target - order matters! -->
115  <Teleport to="#modals">
116    <Modal />
117  </Teleport>
118</template>
119```
120 
121For SSR, ensure consistent ordering or wrap each in `ClientOnly`.
122 
123## Element Plus and UI Library SSR
124 
125Many UI libraries use Teleport internally. Element Plus components that use Teleport include:
126- ElDialog
127- ElDrawer
128- ElTooltip
129- ElDropdown
130- ElSelect
131- ElDatePicker
132 
133```vue
134<template>
135  <!-- These need special SSR handling -->
136  <ClientOnly>
137    <ElDialog v-model="visible">
138      Dialog content
139    </ElDialog>
140  </ClientOnly>
141</template>
142```
143 
144## Known Vue Issues
145 
146- Disabled teleports in fragments can cause hydration mismatches (Vue issue #6152)
147- Nested teleports may cause app to break on hydration (Vue issue #5242)
148 
149## Reference
150- [Vue.js SSR - Teleports](https://vuejs.org/guide/scaling-up/ssr.html#teleports)
151- [Element Plus SSR Guide](https://element-plus.org/en-US/guide/ssr.html)
152- [Nuxt ClientOnly Component](https://nuxt.com/docs/api/components/client-only)
153