{"id":12566,"library":"vue-safe-teleport","title":"Vue Safe Teleport","description":"vue-safe-teleport is a utility package for Vue 3 applications that enhances the built-in `<Teleport>` component to prevent common runtime errors related to target availability. It provides `<SafeTeleport>` and `<TeleportTarget>` components, ensuring that content is only teleported once its designated target DOM element is fully mounted and available. The current stable version is `0.1.2`. While the package is relatively new, its recent bug fixes (e.g., v0.1.2 for import extensions) indicate active maintenance. Key differentiators include its explicit `TeleportTarget` component for robust target registration and a fallback single-frame delay when using `SafeTeleport` with a standard DOM selector, directly addressing the \"Failed to locate Teleport target with selector\" issue that frequently arises from race conditions in component lifecycles. It aims to be a drop-in replacement for `<Teleport>` with added safety.","status":"active","version":"0.1.2","language":"javascript","source_language":"en","source_url":"https://github.com/Akryum/vue-safe-teleport","tags":["javascript","typescript"],"install":[{"cmd":"npm install vue-safe-teleport","lang":"bash","label":"npm"},{"cmd":"yarn add vue-safe-teleport","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-safe-teleport","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for a Vue 3 component library.","package":"vue","optional":false}],"imports":[{"note":"This is the plugin for global registration. `vue-safe-teleport` is an ESM-first package.","wrong":"const VueSafeTeleport = require('vue-safe-teleport')","symbol":"VueSafeTeleport","correct":"import VueSafeTeleport from 'vue-safe-teleport'"},{"note":"SafeTeleport is a named export component. Use it as a drop-in replacement for Vue's built-in <Teleport>.","wrong":"import SafeTeleport from 'vue-safe-teleport'","symbol":"SafeTeleport","correct":"import { SafeTeleport } from 'vue-safe-teleport'"},{"note":"TeleportTarget is a named export component. Use it to explicitly define a teleport target that SafeTeleport will wait for.","symbol":"TeleportTarget","correct":"import { TeleportTarget } from 'vue-safe-teleport'"}],"quickstart":{"code":"// main.js or similar\nimport { createApp } from 'vue';\nimport App from './App.vue';\nimport VueSafeTeleport from 'vue-safe-teleport';\n\nconst app = createApp(App);\napp.use(VueSafeTeleport);\napp.mount('#app');\n\n// App.vue or another component\n<template>\n  <div>\n    <h1>My Vue App</h1>\n    <!-- Define a dedicated teleport target -->\n    <TeleportTarget id=\"modals\" />\n\n    <button @click=\"showModal = true\">Open Safe Teleported Modal</button>\n\n    <!-- Content to be safely teleported to #modals -->\n    <SafeTeleport to=\"#modals\" v-if=\"showModal\">\n      <div style=\"background: white; border: 1px solid #ccc; padding: 20px; position: fixed; top: 50%; left: 50%; transform: translate(-50%, -50%); z-index: 1000;\">\n        <h2>Modal Content</h2>\n        <p>This content is teleported securely.</p>\n        <button @click=\"showModal = false\">Close</button>\n      </div>\n    </SafeTeleport>\n\n    <!-- Example without TeleportTarget, waits one frame -->\n    <SafeTeleport to=\"#floating-element\">\n      <div style=\"position: absolute; bottom: 10px; right: 10px; background: lightblue; padding: 5px;\">\n        Floating Message\n      </div>\n    </SafeTeleport>\n    <div id=\"floating-element\" style=\"position: relative; width: 100px; height: 100px;\"></div>\n  </div>\n</template>\n\n<script setup lang=\"ts\">\nimport { ref } from 'vue';\nimport { SafeTeleport, TeleportTarget } from 'vue-safe-teleport';\n\nconst showModal = ref(false);\n</script>\n\n<style>\n/* Basic styling for demo */\nbody { margin: 0; font-family: sans-serif; }\n#app { padding: 20px; }\n</style>","lang":"typescript","description":"This code demonstrates how to install `vue-safe-teleport`, register it as a Vue plugin, and then use both `TeleportTarget` to define a persistent teleport destination and `SafeTeleport` to send dynamic content to it, preventing common \"target not found\" errors. It also shows using `SafeTeleport` with a standard DOM element, which introduces a single-frame delay if the target isn't immediately present."},"warnings":[{"fix":"Replace `<Teleport to=\"#id\">` with `<SafeTeleport to=\"#id\">`. For best results, also introduce `<TeleportTarget id=\"id\" />` in your root component or layout.","message":"When migrating from Vue's native `<Teleport>`, you must replace `<Teleport>` with `<SafeTeleport>`. While props are largely compatible, the underlying behavior for target resolution changes significantly.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"For explicit and immediate target availability, always pair `<SafeTeleport to=\"#id\">` with a `<TeleportTarget id=\"id\" />` component which notifies `SafeTeleport` when it's ready.","message":"Using `<SafeTeleport>` without a corresponding `<TeleportTarget>` will still resolve the target, but it will implicitly wait one frame if the target is not immediately available. This introduces a slight delay and might not be suitable for performance-critical scenarios where immediate rendering is expected.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Upgrade to `vue-safe-teleport@0.1.2` or later. Ensure your build configuration correctly handles ES modules and import paths, especially with file extensions.","message":"The `v0.1.2` release included a fix for `add extensions to imports`. While intended as a bug fix, users on older versions (pre-0.1.2) in strict module environments or specific build setups might encounter module resolution errors when importing components or the plugin.","severity":"breaking","affected_versions":"<0.1.2"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Replace Vue's `<Teleport>` with `<SafeTeleport>` from `vue-safe-teleport` and ensure a `<TeleportTarget id=\"my-target\" />` component exists and is rendered before `<SafeTeleport>` attempts to mount its content.","cause":"Vue's native Teleport attempts to render content into a target DOM element that has not yet been mounted or is dynamically added later in the component lifecycle, leading to a race condition.","error":"Failed to locate Teleport target with selector \"#my-target\""},{"fix":"Verify the package is correctly installed (`pnpm i vue-safe-teleport`). Ensure you are using ESM `import` statements (e.g., `import { SafeTeleport } from 'vue-safe-teleport'`) and update to `vue-safe-teleport@0.1.2` or later to leverage import path fixes.","cause":"Incorrect import path or module resolution issues, potentially due to missing file extensions in imports in older versions or incorrect CJS/ESM interop.","error":"Module not found: Error: Can't resolve 'vue-safe-teleport'"},{"fix":"For direct component usage, ensure `import { SafeTeleport, TeleportTarget } from 'vue-safe-teleport'` is present. If using the plugin, ensure `app.use(VueSafeTeleport)` is called, which registers them globally.","cause":"Attempting to use `SafeTeleport` or `TeleportTarget` without explicitly importing them as named exports, or without installing the `VueSafeTeleport` plugin globally if not importing them directly.","error":"Property 'SafeTeleport' does not exist on type 'typeof import(\"vue-safe-teleport\")' or 'Component is not defined'."}],"ecosystem":"npm"}