{"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,"search_vec":"'0.1.2':58 '3':14 'activ':75 'ad':134 'address':104 'aim':124 'applic':15 'aris':116 'avail':31,52 'bug':67 'built':20 'built-in':19 'common':25 'compon':22,35,83,121 'condit':119 'content':38 'current':54 'delay':94 'design':44 'differenti':78 'direct':103 'dom':46,101 'drop':129 'drop-in':128 'e.g':69 'element':47 'enhanc':17 'ensur':36 'error':27 'explicit':81 'extens':73 'fail':106 'fallback':90 'fix':68 'frame':93 'frequent':115 'fulli':49 'import':72 'includ':79 'indic':74 'issu':113 'javascript':136 'key':77 'lifecycl':122 'locat':108 'mainten':76 'mount':50 'new':64 'packag':11,61 'prevent':24 'provid':33 'race':118 'recent':66 'registr':87 'relat':28,63 'replac':131 'robust':85 'runtim':26 'safe':2,6 'safeteleport':97 'safeti':135 'selector':102,112 'singl':92 'single-fram':91 'stabl':55 'standard':100 'target':30,45,86,110 'teleport':3,7,41,109 'teleporttarget':82 'typescript':137 'use':96 'util':10 'v0.1.2':70 'version':56 'vue':1,5,13 'vue-safe-teleport':4","created_at":"2026-04-19T13:43:50.652755+00:00","updated_at":"2026-04-19T13:43:50.652755+00:00","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","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/Akryum/vue-safe-teleport","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/vue-safe-teleport","openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}