react-teleporter

react-teleporter

Teleport React components in the same React tree.

👉 Read how to use it to create scalable layouts

👉 Checkout the demo on CodeSandbox

npm install react-teleporter

Example

import { createTeleporter } from "react-teleporter";

const StatusBar = createTeleporter();

function Header() {
  return (
    <header>
      <StatusBar.Target />
    </header>
  );
}

function Page() {
  return (
    <main>
      {/* Teleport "Loading..." into the header */}
      <StatusBar.Source>Loading...</StatusBar.Source>
    </main>
  );
}

function App() {
  return (
    <div>
      <Header />
      <Page />
    </div>
  );
}

Why?

In complex app, you may have to configure a part of the application from another. If you know react-helmet it is the same philosophy. You want to configure a part of your application from another place.

Recipes

Use another target element

Use as property on target to specify another tag.

const Teleporter = createTeleporter()

<Teleporter.Target as="footer" />

Be careful of specifying an element with a ref to a DOM element, it uses React Portals under the hood.

Use props on target

All props are forwarded to target.

const Teleporter = createTeleporter()

<Teleporter.Target onClick={/* ... */} />

Create a custom target ref

Use useTargetRef to create a custom target ref.

const Teleporter = createTeleporter();

function CustomTarget() {
  const targetRef = Teleporter.useTargetRef();
  return <div ref={targetRef} />;
}

Use multiple sources

By default only one Source is allowed to be injected into a Target. Sometimes you may want to inject multiple sources into a single target. Create teleporter with { multiSources: true } option.

const Teleporter = createTeleporter({ multiSources: true })

<Teleporter.Source multiple>
  <a href="#">A link</a>
</Teleporter.Source>

<Teleporter.Source multiple>
  <a href="#">Another link</a>
</Teleporter.Source>

// The target will contains the two links

Use function as children

Useful for having access to the Target element. E.g., to dispatch an event through the Target when something happens in the Source.

const Teleporter = createTeleporter();

const forwardEvent = (element) => (event) =>
  element.dispatch(new Event(event.type, event));

<Teleporter.Source>
  {(element) => <div onClick={forwardEvent(element)}></div>}
</Teleporter.Source>;

API

createTeleporter

createTeleporter is the only method exposed by this package. It returns an object containing a Target, a Source and a useTargetRef to create a custom target.

import { createTeleporter } from "react-teleporter";

const Teleporter = createTeleporter();

Changelog

3.1.0 (2023-03-14)

Features

• support function as Source children (#49) (100d284)