Registry / web-framework / react-teleporter

react-teleporter

library3.2.0jsnpmunverified

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.

web-framework

npm install react-teleporter

github ↗package ↗

INSTALL

IMPORT

SIG · REACT-TELEPORTER

react-teleporter

web-frameworkjavascriptv3.2.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

createTeleporter

✓ import { createTeleporter } from 'react-teleporter'

✗ const { createTeleporter } = require('react-teleporter')

Since v3.0.0, `react-teleporter` is ESM-only. CommonJS `require` syntax is not supported.

Teleporter

✓ import Teleporter from 'react-teleporter'

✗ import { Teleporter } from 'react-teleporter'

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

Teleporter.Source

✓ const MyTeleporter = createTeleporter(); <MyTeleporter.Source>...</MyTeleporter.Source>

The `Source` component is a property of the object returned by `createTeleporter()`.

Teleporter.Target

✓ const MyTeleporter = createTeleporter(); <MyTeleporter.Target />

The `Target` component is a property of the object returned by `createTeleporter()`.

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.

import { createTeleporter } from "react-teleporter"; import React from "react"; import ReactDOM from "react-dom/client"; const StatusBar = createTeleporter(); function Header() { return ( <header style={{ borderBottom: "1px solid #ccc", padding: "10px" }}> <h2>My App Header</h2> <StatusBar.Target /> </header> ); } function Page() { return ( <main style={{ padding: "20px" }}> <p>This is the main content of the page.</p> {/* Teleport "Loading..." into the header */} <StatusBar.Source> <div style={{ color: "blue", fontWeight: "bold" }}>Loading content...</div> </StatusBar.Source> <p>More page content here.</p> </main> ); } function App() { return ( <div> <Header /> <Page /> </div> ); } const rootElement = document.getElementById("root"); if (rootElement) { ReactDOM.createRoot(rootElement).render( <React.StrictMode> <App /> </React.StrictMode> ); } else { console.error("Root element not found"); }

Debug

Known issues

breakingStarting with v3.0.0, `react-teleporter` is distributed as ESM-only. Projects must use ES module import syntax (`import`) instead of CommonJS `require()`.

fix

Update your import statements from `const { createTeleporter } = require('react-teleporter');` to `import { createTeleporter } from 'react-teleporter';` and ensure your build setup supports ESM.

affects: >=3.0.0

breakingType definitions were significantly changed in v3.0.0 to align with the modernized project structure and ESM-only distribution.

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.

affects: >=3.0.0

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

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.

affects: >=2.0.0

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

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 });`.

affects: >=2.0.0

gotchaThe `Source` component can accept a function as children, providing access to the `Target` element. This feature was introduced in v3.1.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>`.

affects: >=3.1.0

Errors

Common errors & fixes

ReferenceError: require is not defined

`react-teleporter` is ESM-only since v3.0.0, and you are attempting to use CommonJS `require()` syntax.

fix

Change your import statement from `const { createTeleporter } = require('react-teleporter');` to `import { createTeleporter } from 'react-teleporter';`.

TypeScript errors related to 'createTeleporter' or its return types.

Your project's `react-teleporter` types are outdated or incompatible with the library version, most commonly seen when migrating to v3.0.0.

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

Console warning: 'React-teleporter: Only one Source is allowed for this Teleporter. Ignoring new Source.' (or similar)

You are attempting to render multiple `<Teleporter.Source>` components for a single `Teleporter` instance without enabling the `multiSources` option.

fix

Initialize your teleporter with `multiSources: true`: `const MyTeleporter = createTeleporter({ multiSources: true });`.

Upgrade

Version history

3.2.0latest on npm

Audit

Dependencies

reactrequiredPeer dependency for React component usage.

react-domrequiredPeer dependency for rendering React components, especially for portals.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/gregberge/react-teleporter ↗

packagehttps://www.npmjs.com/package/react-teleporter ↗