Installations

npm install @react-native-oh-tpl/react-native-shared-element

Developer Guide

BETA

Typescript

Yes

Module System

CommonJS

Node Version

18.20.4

NPM Version

10.7.0 Pull Requests

Open

1

Total

43

Closed

29

Merged

13

Issues

Open

13

Total

84

Closed

71

Releases

25

v0.9.0-rc0 - Support for Expo 52 and RN 0.76

v0.9.0-rc0

Updated on Jan 21, 2025

v0.8.9

Updated on Nov 17, 2023

v0.8.8

Updated on Jan 02, 2023

v0.8.7

Updated on Dec 23, 2022

v0.8.6

Updated on Dec 21, 2022

v0.8.5

Updated on Jul 29, 2022

View All 25 releases

Languages

7

TypeScript

Objective-C

Java

C#

JavaScript

C

Ruby

TypeScript (53.96%)

Objective-C (22.41%)

Java (21.61%)

C# (1.05%)

JavaScript (0.41%)

C (0.36%)

Ruby (0.2%)

Developer

IjzerenHein

Download Statistics

Total Downloads

0

Last Day

0

Last Week

0

Last Month

0

Last Year

0

GitHub Statistics

MIT License

2,282 Stars

516 Commits

106 Forks

27 Watchers

4 Branches

7 Contributors

Updated on Jul 10, 2025

Maintainers

11

View All 7 Contributors

Package Meta Information

Latest Version

0.8.9-0.0.6

Package Id

@react-native-oh-tpl/react-native-shared-element@0.8.9-0.0.6

Unpacked Size

570.92 kB

Size

285.08 kB

File Count

149

NPM Version

10.7.0

Node Version

18.20.4

Published on

Apr 24, 2025

Total Downloads

Cumulative downloads

Total Downloads

NaN

Last Day

0%

NaN

Compared to previous day

Last Week

0%

NaN

Compared to previous week

Last Month

0%

NaN

Compared to previous month

Last Year

0%

NaN

Compared to previous year

Weekly Downloads

Monthly Downloads

Yearly Downloads

Dependencies

1

react-native-shared-element

Dev Dependencies

5

@types/react @types/react-native eslint expo-module-scripts prettier

react-native-shared-element

Native shared element transition "primitives" for react-native 💫

This library in itself is not a Navigation- or Router library. Instead, it provides a set of comprehensive full native building blocks for performing shared element transitions in Router- or Transition libraries. If you are looking for the React Navigation binding, you can find it here.

MagicMoveGif-iOS MagicMoveGif-Android

Motivation

Shared-element transitions add shine to your app but can be hard to do in practise. It's possible to achieve some nice transitions by building custom modals and using the core react-native API, But this also brings with it many restrictions. Things like resizing an image or making sure no "flicker" occurs even an older Android devices can be a real challenge.

This library solves that problem through an all native implementation which is very close to the metal of the OS. It solves the problem by providing a set of "primitives", which don't require any back and forth passes over the react-native bridge. This way, the best possible performance is achieved and better image transitions can be accomplished. The following list is an impression of the kinds of problems that are solved through the native implementation.

Installation

1yarn add react-native-shared-element

As of Expo SDK 49, react-native-shared-element is no longer shipped with Expo Go. If you want to use this library with Expo managed projects, create a development build.

Basic usage

1import {
2  SharedElement,
3  SharedElementTransition,
4  nodeFromRef
5} from 'react-native-shared-element';
6
7// Scene 1
8let startAncestor;
9let startNode;
10<View ref={ref => startAncestor = nodeFromRef(ref)}>
11  ...
12  <SharedElement onNode={node => startNode = node}>
13    <Image style={styles.image} source={...} />
14  </SharedElement>
15  ...
16</View>
17
18
19// Scene2
20let endAncestor;
21let endNode;
22<View ref={ref => endAncestor = nodeFromRef(ref)}>
23  ...
24  <SharedElement onNode={node => endNode = node}>
25    <Image style={styles.image} source={...} />
26  </SharedElement>
27  ...
28</View>
29
30// Render overlay in front of screen
31const position = new Animated.Value(0);
32<View style={StyleSheet.absoluteFill}>
33  <SharedElementTransition
34    start={{
35      node: startNode,
36      ancestor: startAncestor
37    }}
38    end={{
39      node: endNode,
40      ancestor: endAncestor
41    }}
42    position={position}
43    animation='move'
44    resize='auto'
45    align='auto'
46     />
47</View>

How it works

react-native-shared-element is a "primitive" that runs shared element transitions entirely native without requiring any passes over the JavaScript bridge. It works by taking in a start- and end node, which are obtained using the <SharedElement> component.

Whenever a transition between screens occurs (e.g. performed by a router/navigator), a view in front of the app should be rendered to host the shared element transition. The position prop is used to interpolate between the start- and end nodes, 0 meaning "Show the start node" and 1 meaning "Show the end node".

Whenever the <SharedElementTransition> component is rendered, it performs the following tasks:

Measure the size and position of the provided element
Obtain the styles of the elements
Obtain the visual content of the elements (e.g. an image or a view snapshot)
Render a visual copy of the start element at its current position
Hide the original elements whenever the visual copy are on the screen
Monitor the position prop and render the shared element transition accordingly
Upon unmount, unhide the original elements

You typically do not use this component directly, but instead use a Router or Transition-engine which provides a higher-level API. See ./example/src/components/Router.tsx for an example implementation of a simple stack router using shared element transitions.

API Documentation

SharedElement

The <SharedElement> component accepts a single child and returns a node to it through the onNode event handler. The child must correspond to a "real" View which exists in the native view hierarchy.

Props

Property	Type	Description
`children`	`element`	A single child component, which must map to a real view in the native view hierarchy
`onNode`	`function`	Event handler that sets or unsets the node-handle
`View props...`		Other props supported by View

SharedElementTransition

The <SharedElementTransition> component executes a shared element transition natively. It natively performs the following tasks: measure, clone, hide, animate and unhide, to achieve the best results.

Props

Property	Type	Description
`start`	`{ node: SharedElementNode, ancestor: SharedElementNode }`	Start node- and ancestor
`end`	`{ node: SharedElementNode, ancestor: SharedElementNode }`	End node- and ancestor
`position`	`number` \| `Animated.Value` \| `Reanimated.Value`	Interpolated position (0..1), between the start- and end nodes
`animation`	SharedElementAnimation	Type of animation, e.g move start element or cross-fade between start- and end elements (default = `move`)
`resize`	SharedElementResize	Resize behavior (default = `auto`)
`align`	SharedElementAlign	Alignment behavior (default = `auto`)
`debug`	`boolean`	Renders debug overlays for diagnosing measuring and animations
`onMeasure`	`function`	Event handler that is called when nodes have been measured and snapshotted

Transitions effects

The transition effect can be controlled using the animation, resize and align props. In most cases you should leave these to their default values for the best possible results.

If however the start- element and end elements are visually different, then it can make sense to choose different values. For instance, if you are transitioning from a <Text> with a white color to a <Text> with a black color, then using animation="fade" will create a cross-fade between them.

Another case is when you have a single-line of <Text> in the start- view and a full description in the end- view. A stretch effect would in this case not look good, because the end- element is much larger in size compared the start- element. In this case you can use resize="clip" and align="left-top" to create a text reveal effect.

SharedElementAnimation

Animation	Description
`move`	Moves the start- element to the end position
`fade`	Cross-fades between the start- and end elements
`fade-in`	Fade-in the end element coming from the start position (start-element is not visible)
`fade-out`	Fade-out the start element to the end position (end-element is not visible)

SharedElementResize

Resize	Description
`auto`	Automatically selects the default resize behavior. For images this will perform the best possible transition based on the `resizeMode` of the image. For other kinds of views, this will default to `stretch`.
`stretch`	Stretches the element to the same shape and size of the other element. If the aspect-ratio of the content differs, you may see stretching. In that case consider the `clip` or `none` resize options.
`clip`	Do not resize, but clip the content to the size of the other content. This option is for instance useful in combination with `<Text>` components, where you want to reveal more text.
`none`	Do not resize the content. When combined with `fade`, this creates a plain cross-fade effect without any resizing or clipping

SharedElementAlign

auto, left-center, left-top, left-right, right-center, right-top, right-right, center-top center-center, center-bottom

When auto is selected, the default alignment strategy is used, which is center-center.

Example apps

The main example & test app is located in ./example and serves as an exploration and testing tool. It features a custom stack router which implements the shared element primitives. It also implements the react-navigation binding and serves as a testing tool for that.
Demo app for react-navigation
Simple demo app using RN60 and the react-navigation binding

License

Shared element transition library is licensed under The MIT License.

Credits

This project is supported by amazing people from Expo.io

Changes in maintenance

Both react-native-shared-element and react-navigation-shared-element are always looking for new Maintainers. It is no longer possible for me (@author) to maintain these repositories. Please reach out to me personally if you have ideas or suggestions.

Read the full statement here.

No vulnerabilities found.

10

Dangerous-Workflow

Determines if the project's GitHub Action workflows avoid dangerous patterns.

10

Binary-Artifacts

Determines if the project has generated executable (binary) artifacts in the source repository.

10

License

Determines if the project has defined a license.

0

Code-Review

Determines if the project requires human code review before pull requests (aka merge requests) are merged.

0

Maintained

Determines if the project is "actively maintained".

0

Token-Permissions

Determines if the project's workflows follow the principle of least privilege.

0

CII-Best-Practices

Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.

0

Security-Policy

Determines if the project has published a security policy.

0

Fuzzing

Determines if the project uses fuzzing.

0

Pinned-Dependencies

Determines if the project has declared and pinned the dependencies of its build process.

0

Branch-Protection

Determines if the default and release branches are protected with GitHub's branch protection settings.

0

SAST

Determines if the project uses static code analysis.

0

Vulnerabilities

Determines if the project has open, known unfixed vulnerabilities.

Score

2.5

/10

Last Scanned on 2025-07-07

The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.

Learn More