Vue Safe Teleport

Common errors

• Failed to locate Teleport target with selector "#my-target"

  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.
  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.

• Module not found: Error: Can't resolve 'vue-safe-teleport'

  cause Incorrect import path or module resolution issues, potentially due to missing file extensions in imports in older versions or incorrect CJS/ESM interop.
  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.

• Property 'SafeTeleport' does not exist on type 'typeof import("vue-safe-teleport")' or 'Component is not defined'.

  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.
  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.

Warnings

• gotcha 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.
  Fix: Replace `<Teleport to="#id">` with `<SafeTeleport to="#id">`. For best results, also introduce `<TeleportTarget id="id" />` in your root component or layout.
• gotcha 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.
  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.
• breaking 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.
  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.

Install

• npm install vue-safe-teleport npm
• yarn add vue-safe-teleport yarn
• pnpm add vue-safe-teleport pnpm

Imports

• VueSafeTeleport
  wrong:

  const VueSafeTeleport = require('vue-safe-teleport')

  correct:

  import VueSafeTeleport from 'vue-safe-teleport'

  This is the plugin for global registration. `vue-safe-teleport` is an ESM-first package.
• SafeTeleport
  wrong:

  import SafeTeleport from 'vue-safe-teleport'

  correct:

  import { SafeTeleport } from 'vue-safe-teleport'

  SafeTeleport is a named export component. Use it as a drop-in replacement for Vue's built-in <Teleport>.
• TeleportTarget

  import { TeleportTarget } from 'vue-safe-teleport'

  TeleportTarget is a named export component. Use it to explicitly define a teleport target that SafeTeleport will wait for.

Quickstart

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.

// main.js or similar
import { createApp } from 'vue';
import App from './App.vue';
import VueSafeTeleport from 'vue-safe-teleport';

const app = createApp(App);
app.use(VueSafeTeleport);
app.mount('#app');

// App.vue or another component
<template>
  <div>
    <h1>My Vue App</h1>
    <!-- Define a dedicated teleport target -->
    <TeleportTarget id="modals" />

    <button @click="showModal = true">Open Safe Teleported Modal</button>

    <!-- Content to be safely teleported to #modals -->
    <SafeTeleport to="#modals" v-if="showModal">
      <div style="background: white; border: 1px solid #ccc; padding: 20px; position: fixed; top: 50%; left: 50%; transform: translate(-50%, -50%); z-index: 1000;">
        <h2>Modal Content</h2>
        <p>This content is teleported securely.</p>
        <button @click="showModal = false">Close</button>
      </div>
    </SafeTeleport>

    <!-- Example without TeleportTarget, waits one frame -->
    <SafeTeleport to="#floating-element">
      <div style="position: absolute; bottom: 10px; right: 10px; background: lightblue; padding: 5px;">
        Floating Message
      </div>
    </SafeTeleport>
    <div id="floating-element" style="position: relative; width: 100px; height: 100px;"></div>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { SafeTeleport, TeleportTarget } from 'vue-safe-teleport';

const showModal = ref(false);
</script>

<style>
/* Basic styling for demo */
body { margin: 0; font-family: sans-serif; }
#app { padding: 20px; }
</style>