react-native-screen-choreography

Shared elements. Connected screens.

Choreograph shared elements, companion reveals, and custom back gestures with one progress value. Keep real content alive as it moves between React Native screens.

Read the docs · Get started · API reference · Examples

Pre-1.0: the public API is converging, but minor versions can introduce breaking changes.

   

One owner. One receiving target.

The source owns a component. The destination declares its bounds. The library moves the same native subtree through an overlay into the destination using react-native-teleport; React state and context stay with the original owner.

// Source screen: render content once.
<SharedElement id="hero" groupId="photo.aurora" style={styles.tile}>
  <PhotoHero />
</SharedElement>

// Destination screen: an empty, measurable receiving target.
<SharedElement.Target
  id="hero"
  groupId="photo.aurora"
  style={styles.hero}
/>

The owner screen must remain mounted. Pair both endpoints with the same element ID and group, wrap routes in ChoreographyScreen, and navigate with that group. Follow the complete two-screen example for imports, provider placement, navigator configuration, and Back.

Installation

npm install react-native-screen-choreography

The library also needs native peer dependencies and a native app rebuild. Follow the installation guide for your navigation setup before running the example above.

• Platforms: iOS and Android, React Native ≥0.81 with the New Architecture / Fabric.
• Runtime: React ≥18, Reanimated ≥4, Worklets ≥0.8, Screens ≥4, and Teleport ≥1.2. Choose mutually compatible peer versions; these lower bounds are not a full tested compatibility matrix.
• Navigation: React Navigation native-stack ≥6 (validated on 7.x), or Expo Router ≥56.1.1.
• Expo: a development build is required. Expo Go does not include the custom native host.

The checked-in examples use React Native 0.83 and Expo SDK 57. Native-stack swipe progress is not connected automatically; use interactive Back for custom gesture control.

Documentation

Start here	Build with motion	Go deeper
Introduction	Transition recipes	Component reference
Installation	Interactive Back	Navigation reference
Your first transition	Readiness and loading	Transitions reference
Expo Router	Troubleshooting	Hooks and utilities

Contributor material: runtime architecture, performance measurements, and contributing.

Example apps

Both integrations use the same shared demo screens and module-scoped defineTransition recipes. Browse the demo gallery for recordings and links to their source.

• React Navigation example setup
• Expo Router example setup
• Shared example source

Work on the documentation

The documentation is a static VitePress site. Most edits are ordinary Markdown; native dependencies are not needed to build it. Node.js 22 or newer is required for the docs toolchain.

yarn install
yarn docs:dev
yarn docs:build

The docs are a Yarn workspace. You can also run yarn dev from docs/. For documentation-only work, use yarn workspaces focus screen-choreography-docs instead of yarn install to install only the docs dependencies.

License

MIT