# react-teleporter

> Teleport React components in the same React tree.

Latest version **3.2.0** (published 2025-05-23) · MIT license · 0 weekly downloads

## Install

```sh
npm install react-teleporter
pnpm add react-teleporter
yarn add react-teleporter
bun add react-teleporter
```

## Health

**Score 40/100 (D)** — status: maintenance-mode.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.2.0 |
| Published | 2025-05-23 |
| First published | 2019-06-10 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Dependencies | 0 |
| Unpacked size | 12.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1150 |
| Maintainers | neoziro |
| Keywords | react, portal, teleport, tunnel |

## Links

- npm: https://www.npmjs.com/package/react-teleporter
- Repository: https://github.com/gregberge/react-teleporter
- Homepage: https://github.com/gregberge/react-teleporter#readme
- Issues: https://github.com/gregberge/react-teleporter/issues
- Funding: https://github.com/sponsors/gregberge
- npm.io page: https://npm.io/package/react-teleporter

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 3.2.0 (latest) — 2025-05-23
- 3.1.0 — 2023-03-14
- 3.0.2 — 2022-06-27
- 3.0.1 — 2022-06-19
- 3.0.0 — 2022-06-18
- 2.2.1 — 2021-06-21
- 2.2.0 — 2021-03-27
- 2.1.1 — 2020-03-19
- 2.1.0 — 2020-03-07
- 2.0.1 — 2019-12-18
- 2.0.0 — 2019-12-18
- 1.1.1 — 2019-09-22
- 1.1.0 — 2019-06-12
- 1.0.0 — 2019-06-10

## README

# react-teleporter

[![License](https://img.shields.io/npm/l/react-teleporter.svg)](https://github.com/gregberge/react-teleporter/blob/main/LICENSE)
[![npm package](https://img.shields.io/npm/v/react-teleporter/latest.svg)](https://www.npmjs.com/package/react-teleporter)
[![npm bundle size](https://img.shields.io/bundlephobia/minzip/react-teleporter)](https://bundlephobia.com/package/react-teleporter)
[![CI](https://github.com/gregberge/react-teleporter/actions/workflows/ci.yml/badge.svg)](https://github.com/gregberge/react-teleporter/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/gregberge/react-teleporter/branch/main/graph/badge.svg)](https://codecov.io/gh/gregberge/react-teleporter)

Teleport React components in the same React tree.

👉 [**Read how to use it to create scalable layouts**](https://gregberge.com/blog/react-scalable-layout)

👉 [**Checkout the demo on CodeSandbox**](https://codesandbox.io/s/react-teleporter-demo-ryklv)

```bash
npm install react-teleporter
```

## Example

```js
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](https://github.com/nfl/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.

```js
const Teleporter = createTeleporter()

<Teleporter.Target as="footer" />
```

> Be careful of specifying an element with a ref to a DOM element, it uses [React Portals](https://reactjs.org/docs/portals.html) under the hood.

### Use props on target

All props are forwarded to target.

```js
const Teleporter = createTeleporter()

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

### Create a custom target ref

Use `useTargetRef` to create a custom target ref.

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

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

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

```js
import { createTeleporter } from "react-teleporter";

const Teleporter = createTeleporter();
```

---
_Source: https://npm.io/package/react-teleporter · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
