{"id":11879,"library":"react-teleporter","title":"React Teleporter","description":"React Teleporter is a library designed for seamlessly moving or \"teleporting\" React components within the same React component tree. Unlike standard React Portals, which can render children into a different DOM node outside the current DOM hierarchy, `react-teleporter` maintains the logical connection within the same React tree. This distinction simplifies state and context management, as components remain within their original React context, making it ideal for managing complex layouts where content needs to appear in a different visual location than where it's defined. Inspired by the configuration philosophy of `react-helmet`, it allows for configuring parts of an application from a separate, perhaps deeply nested, location. The current stable version is 3.2.0, with regular minor and patch releases to support new React versions (currently up to React 19) and add features like `function as children` for `Source` components. Major versions, such as v3.0.0, introduce significant breaking changes, notably the transition to an ESM-only distribution. The library exports `createTeleporter`, which generates a `Source` and `Target` pair, enabling content defined within a `Source` component to be rendered at the `Target`'s designated position.","status":"active","version":"3.2.0","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/gregberge/react-teleporter","tags":["javascript","react","portal","teleport","tunnel","typescript"],"install":[{"cmd":"npm install react-teleporter","lang":"bash","label":"npm"},{"cmd":"yarn add react-teleporter","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-teleporter","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for React component usage.","package":"react","optional":false},{"reason":"Peer dependency for rendering React components, especially for portals.","package":"react-dom","optional":false}],"imports":[{"note":"Since v3.0.0, `react-teleporter` is ESM-only. CommonJS `require` syntax is not supported.","wrong":"const { createTeleporter } = require('react-teleporter')","symbol":"createTeleporter","correct":"import { createTeleporter } from 'react-teleporter'"},{"note":"While `createTeleporter` is the primary named export, a default export `Teleporter` was added in v3.0.2 for compatibility. The object returned by `createTeleporter()` is commonly named `Teleporter`.","wrong":"import { Teleporter } from 'react-teleporter'","symbol":"Teleporter","correct":"import Teleporter from 'react-teleporter'"},{"note":"The `Source` component is a property of the object returned by `createTeleporter()`.","symbol":"Teleporter.Source","correct":"const MyTeleporter = createTeleporter(); <MyTeleporter.Source>...</MyTeleporter.Source>"},{"note":"The `Target` component is a property of the object returned by `createTeleporter()`.","symbol":"Teleporter.Target","correct":"const MyTeleporter = createTeleporter(); <MyTeleporter.Target />"}],"quickstart":{"code":"import { createTeleporter } from \"react-teleporter\";\nimport React from \"react\";\nimport ReactDOM from \"react-dom/client\";\n\nconst StatusBar = createTeleporter();\n\nfunction Header() {\n  return (\n    <header style={{ borderBottom: \"1px solid #ccc\", padding: \"10px\" }}>\n      <h2>My App Header</h2>\n      <StatusBar.Target />\n    </header>\n  );\n}\n\nfunction Page() {\n  return (\n    <main style={{ padding: \"20px\" }}>\n      <p>This is the main content of the page.</p>\n      {/* Teleport \"Loading...\" into the header */}\n      <StatusBar.Source>\n        <div style={{ color: \"blue\", fontWeight: \"bold\" }}>Loading content...</div>\n      </StatusBar.Source>\n      <p>More page content here.</p>\n    </main>\n  );\n}\n\nfunction App() {\n  return (\n    <div>\n      <Header />\n      <Page />\n    </div>\n  );\n}\n\nconst rootElement = document.getElementById(\"root\");\nif (rootElement) {\n  ReactDOM.createRoot(rootElement).render(\n    <React.StrictMode>\n      <App />\n    </React.StrictMode>\n  );\n} else {\n    console.error(\"Root element not found\");\n}","lang":"typescript","description":"This quickstart demonstrates how to use `createTeleporter` to define a `StatusBar` teleporter, allowing content from a `Source` component within `Page` to be rendered at a `Target` location inside `Header`, effectively moving UI elements across the React tree without prop drilling."},"warnings":[{"fix":"Update your import statements from `const { createTeleporter } = require('react-teleporter');` to `import { createTeleporter } from 'react-teleporter';` and ensure your build setup supports ESM.","message":"Starting with v3.0.0, `react-teleporter` is distributed as ESM-only. Projects must use ES module import syntax (`import`) instead of CommonJS `require()`.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Review your TypeScript code and update type annotations and usage of `createTeleporter` and its returned components according to the new type definitions. Refer to the official documentation or example usages for v3.x.","message":"Type definitions were significantly changed in v3.0.0 to align with the modernized project structure and ESM-only distribution.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Ensure that if you specify a custom DOM element with `as`, it correctly handles refs as expected by React Portals, or use `useTargetRef` for custom target elements where direct DOM manipulation is required.","message":"`react-teleporter` uses React Portals under the hood when rendering to a target element. Be cautious when specifying the `as` prop on `Target` with a custom DOM element, as incorrect usage with refs might lead to unexpected behavior or compatibility issues.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"To enable multiple `Source` components to render content simultaneously at a `Target`, initialize your teleporter with the `multiSources` option: `const Teleporter = createTeleporter({ multiSources: true });`.","message":"By default, a `Teleporter` instance only allows a single `Source` component to be active at a time. If multiple `Source` components are rendered, only the latest one will be displayed, or a warning might be issued.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"If using a functional child for `Source`, ensure your `react-teleporter` version is 3.1.0 or newer. Example: `<Teleporter.Source>{(element) => <div onClick={forwardEvent(element)}></div>}</Teleporter.Source>`.","message":"The `Source` component can accept a function as children, providing access to the `Target` element. This feature was introduced in v3.1.0.","severity":"gotcha","affected_versions":">=3.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change your import statement from `const { createTeleporter } = require('react-teleporter');` to `import { createTeleporter } from 'react-teleporter';`.","cause":"`react-teleporter` is ESM-only since v3.0.0, and you are attempting to use CommonJS `require()` syntax.","error":"ReferenceError: require is not defined"},{"fix":"Ensure you are using `react-teleporter@^3.0.0` or later and update your TypeScript configuration and code to reflect the new type definitions. Run `npm install react-teleporter@latest` or `yarn add react-teleporter@latest`.","cause":"Your project's `react-teleporter` types are outdated or incompatible with the library version, most commonly seen when migrating to v3.0.0.","error":"TypeScript errors related to 'createTeleporter' or its return types."},{"fix":"Initialize your teleporter with `multiSources: true`: `const MyTeleporter = createTeleporter({ multiSources: true });`.","cause":"You are attempting to render multiple `<Teleporter.Source>` components for a single `Teleporter` instance without enabling the `multiSources` option.","error":"Console warning: 'React-teleporter: Only one Source is allowed for this Teleporter. Ignoring new Source.' (or similar)"}],"ecosystem":"npm"}