react-native-teleport

react-native-teleport is a library that provides true native portals for React Native. Unlike JavaScript-based portal libraries that re-parent components in the JS layer, react-native-teleport physically moves the view in the native view hierarchy while keeping the component logically within its original position in the React tree.

Key Benefits

• Preserves React Context: Because the component stays in its original React tree position, access to themes, navigation, i18n, and other React Context values is maintained.
• Native Performance & Layout: Moving the view in the native hierarchy ensures correct z-order, layout behavior, and platform-native performance.
• Cross-Platform: Works on iOS, Android, and Web.
• Teleporting: Supports re-parenting existing views without unmounting them, allowing you to move views in native space without breaking React logic.

To implement fluid, Instagram-quality shared transitions (e.g., moving a video or image from a feed to a full-screen view), use the following architectural patterns:

1. Dynamic Teleportation: Use the <Portal> component and dynamically change its hostName prop. This allows you to move a component (like a video player) between different parts of the UI tree (e.g., from a feed to an overlay or a specific screen) without unmounting it, preserving its internal state.
2. Layout Preservation: Use a fixed-height container in the source location (the feed) to preserve the scroll position of the list while the content is being teleported away.
3. Modal Presentation: Use transparentModal for navigation. This keeps the underlying screen (the feed) visible during the transition, which is essential for seamless visual continuity and enables gesture-based interactions.
4. State Coordination: Use a state management tool like Zustand combined with Reanimated SharedValue to coordinate animation states across different components. This ensures the animation logic stays on the UI thread for high performance.
5. Precise Positioning: Use measureInWindow to capture the exact screen coordinates of the source content. This allows the animation to start from the precise location of the element in the feed and transition smoothly to its new destination.

This pattern is applicable to any content type, including images, cards, or avatars.

While standard React reconciliation uses create, update, and destroy, react-native-teleport introduces a fourth operation: move. This allows you to re-parent components without unmounting or remounting them, which is critical for maintaining state in heavy components (like Video or Lottie).

Key Use Cases:

1. Pre-render Components Offscreen

You can render expensive components off-screen and move them into view only when needed. This avoids setup delays for complex overlays, modals, or bottom sheets.

// Pre-render the editor off-screen
<Portal hostName={used ? "editor" : undefined}>
  <ExpensiveRichTextEditor />
</Portal>

// Later, when user triggers an action, simply move it into view
// No re-rendering, no state loss, just a native view reposition

2. Re-use Views Between Screens

You can render the same component instance on multiple screens and seamlessly move it as users navigate. This enables shared-element-style transitions and avoids the performance cost of re-creating heavy components during navigation transitions.

The library manages transitions between local rendering and teleportation to ensure children survive host changes:

• Host mounts after Portal: Children move from local rendering into the new host automatically via native re-parenting (no React re-render).
• Host unmounts while Portal is alive: Children are pulled back to the Portal's local position. They are not destroyed, and all component state, refs, and imperative native state (e.g., video playback, scroll position) are preserved.
• Host remounts: Children follow the host. A remounted host with the same name picks up exactly where the previous cycle left off.
• Portal's hostName changes: Children migrate to the new target. If the new target is missing, they fall back to local rendering.
• Portal unmounts: Children unmount with the Portal, regardless of whether they were currently teleported or local. The host does not keep orphaned children.
• Host unmounts: The host disappears, but Portals targeting it survive by falling back to local rendering.

You can eliminate loading spinners for expensive components (like WebViews, maps, or charts) by rendering them offscreen at app startup and teleporting them into view only when needed.

The Pattern

1. At App Startup: Mount the heavy component inside a <Portal> within a hidden, offscreen container (e.g., using position: 'absolute', top: -9999). Assign the Portal a specific hostName.
2. Background Loading: Because no matching <PortalHost> exists yet, the component renders in its place (offscreen) and initializes (downloads JS, parses, etc.) while the user is on other screens.
3. On Navigation: When the user navigates to the target screen, mount a <PortalHost> with the matching name.
4. Instant Rendering: The component teleports into the host. Since react-native-teleport re-parents (moves) the native view rather than re-mounting it, the component appears instantly with its state (scroll position, user input, loaded scripts) fully preserved.
5. On Unmount: When the <PortalHost> unmounts, the content automatically returns to the offscreen <Portal>.

// 1. Offscreen Portal at App Root
<View style={{ position: 'absolute', top: -9999 }}>
  <Portal hostName="my-heavy-component">
    <ExpensiveComponent />
  </Portal>
</View>

// 2. On the target screen
<PortalHost name="my-heavy-component" />

To achieve smooth, uninterrupted transitions (like expanding a video from a feed into a full-screen player), react-native-teleport uses a re-parenting strategy rather than unmounting and remounting components.

The Workflow

1. Initial State: The video component lives inside a <Portal> within the source screen (e.g., the Feed).
2. Transition Start: When a user interacts, the video is teleported to an overlay layer that sits above all screens.
3. Animation: While in the overlay, the video is animated from its original card size to full-screen dimensions.
4. Transition End: Once the animation completes, the video is teleported into a <PortalHost> inside the destination screen (e.g., the Reels viewer).
5. Reversal: Going back reverses this: teleport to overlay $\rightarrow$ animate back to card size $\rightarrow$ return to the original screen.

Because the component is moved in the native view hierarchy instead of being destroyed and recreated, playback is never interrupted and animations remain fluid.

Feed (in-place) ──tap──▶ Overlay (animating) ──done──▶ Reels (in-place)
                                                              │
                         Overlay (animating) ◀──back──────────┘
                                                            │
Feed (in-place) ◀──done──────┘