React Teleporter

Common errors

• ReferenceError: require is not defined

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

  cause 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)

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

Warnings

• breaking Starting 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.
• breaking Type 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.
• 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.
• gotcha 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.
  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 });`.
• gotcha The `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>`.

Install

• npm install react-teleporter npm
• yarn add react-teleporter yarn
• pnpm add react-teleporter pnpm

Imports

• createTeleporter
  wrong:

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

  correct:

  import { createTeleporter } from 'react-teleporter'

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

  import { Teleporter } from 'react-teleporter'

  correct:

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

Quickstart

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");
}