https://github.com/pmndrs/tunnel-rat

🐀 Non gratum anus rodentum
https://github.com/pmndrs/tunnel-rat

Last synced: 27 days ago
JSON representation

🐀 Non gratum anus rodentum

• Host: GitHub
• URL: https://github.com/pmndrs/tunnel-rat
• Owner: pmndrs
• License: mit
• Created: 2022-01-21T12:08:15.000Z (almost 3 years ago)
• Default Branch: main
• Last Pushed: 2024-01-15T22:37:05.000Z (10 months ago)
• Last Synced: 2024-05-01T11:29:10.730Z (6 months ago)
• Language: TypeScript
• Homepage:
• Size: 480 KB
• Stars: 319
• Watchers: 6
• Forks: 9
• Open Issues: 6
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • License: LICENSE

Awesome Lists containing this project

README

        


    



[![Version](https://img.shields.io/npm/v/tunnel-rat?style=for-the-badge)](https://www.npmjs.com/package/tunnel-rat)

[![Downloads](https://img.shields.io/npm/dt/tunnel-rat.svg?style=for-the-badge)](https://www.npmjs.com/package/tunnel-rat)

[![Bundle Size](https://img.shields.io/bundlephobia/min/tunnel-rat?label=bundle%20size&style=for-the-badge)](https://bundlephobia.com/result?p=tunnel-rat)

## Tunnel Rat

- Digs tunnels for React elements to **go in** and **appear somewhere else**!

- Works across **separate renderers** – use it to easily **render HTML elements from within your @react-three/fiber application**!

- Squeak! 🐀

## Examples & Sandboxes

- https://codesandbox.io/s/basic-demo-forked-kxq8g

- https://codesandbox.io/s/tunnel-rat-demo-ceupre

## Usage

Create a tunnel:

```tsx

import tunnel from 'tunnel-rat'

const t = tunnel()

```

Use the tunnel's `In` component to send one or more elements into the tunnel:

```tsx

  
Very cool!

  
These will appear somewhere else!


```

Somewhere else, use the tunnel's `Out` component to render them:

```tsx

```

## Examples

This example describes a simple React app that has both a HTML UI as well as a @react-three/fiber 3D scene. Each of these is rendered using separate React renderers, which traditionally makes emitting HTML from within the Canvas a bit of a pain; but thanks to tunnel-rat, this is now super easy!

```jsx

import { Canvas } from '@react-three/fiber'

import tunnel from 'tunnel-rat'

/* Create a tunnel. */

const ui = tunnel()

const App = () => (

  


    


      {/* Anything that goes into the tunnel, we want to render here. */}

      

    


    {/* Here we're entering the part of the app that is driven by

    @react-three/fiber, where all children of the  component

    are rendered by an entirely separate React renderer, which would

    typically not allow the use of HTML tags. */}

    

      {/* Let's send something into the tunnel! */}

      

        
Hi, I'm a cube!

      


      

        

        

      

      {/* You can send multiple things through the tunnel, and

      they will all show up in the order that you've defined them in! */}

      

        
And I'm a sphere!

      


      

        

        

      

    

  

)

```


Of course, the whole thing also works the other way around:

```jsx

import { Canvas } from '@react-three/fiber'

import tunnel from 'tunnel-rat'

/* Create a tunnel. */

const three = tunnel()

const App = () => (

  


    


      {/* Let's beam something into the R3F Canvas! */}

      

        

          

          

        

      

    


    

      {/* Render anything sent through the tunnel! */}

      

    

  

)

```


## Gotchas

If you have multiple in's React may loose track of object order and even mismatch objects, especially if the root elements are of the same type. Make sure you use keys, always treat multiple in's as a list!

```jsx

  
foo


...

  
bar


```