--- title: Teleport Target Must Exist Before Mount impact: HIGH impactDescription: Teleport will fail silently or throw errors if target element doesn't exist when component mounts type: gotcha tags: [vue3, teleport, modal, dom, lifecycle] --- # Teleport Target Must Exist Before Mount **Impact: HIGH** - The teleport `to` target must already exist in the DOM when the `` component is mounted. If the target doesn't exist, Vue will throw an error and the teleported content won't render. This is a common source of bugs when using modals, tooltips, or other teleported UI elements, especially when targeting Vue-rendered elements. ## Task Checklist - [ ] Ensure teleport target exists in the DOM before `` mounts - [ ] Place teleport containers (e.g., `#modals`, `#tooltips`) in `index.html` outside the Vue app - [ ] If targeting Vue-rendered elements, ensure they mount before the Teleport - [ ] Use Vue 3.5+ `defer` prop when target is rendered later in the same component tree **Incorrect:** ```vue ``` **Correct - Option 1: External container in index.html:** ```html

``` ```vue ``` **Correct - Option 2: Teleport to body:** ```vue ``` **Correct - Option 3: Vue 3.5+ defer prop:** ```vue ``` ## Defer Prop Limitations (Vue 3.5+) The `defer` prop only waits for elements rendered in the **same mount/update tick**: ```vue ``` ## Common Patterns ### Recommended: Centralized Teleport Containers ```html

``` ## Reference - [Vue.js Teleport - Using with Vue-rendered Targets](https://vuejs.org/guide/built-ins/teleport.html#using-with-vue-rendered-targets) - [Vue.js Teleport - Deferred Teleport](https://vuejs.org/guide/built-ins/teleport.html#deferred-teleport)