Animating elements between screens

This guide covers how to animate elements between screens. This feature is known as a Shared Element Transition and it's implemented in the @react-navigation/native-stack with React Native Reanimated.

warning

Shared Element Transitions are an experimental feature not recommended for production use yet.

Architecture support:

• Reanimated 3 supports Shared Element Transitions on the Old Architecture (Paper).
• Reanimated 4 supports them on the New Architecture (Fabric) since 4.2.0, but the feature is behind a feature flag. You need to enable the ENABLE_SHARED_ELEMENT_TRANSITIONS feature flag to use it.

Check the Reanimated documentation for details and send feedback to the Reanimated team

Pre-requisites

Before continuing this guide make sure your app meets these criteria:

• You are using @react-navigation/native-stack. JS-based @react-navigation/stack or other navigators are not supported.
• You have react-native-reanimated v3.0.0 or higher installed and configured.
• If you are using Reanimated 4 (New Architecture), you must enable the ENABLE_SHARED_ELEMENT_TRANSITIONS feature flag.

Minimal example

To create a shared transition:

1. Use Animated components imported from react-native-reanimated.
2. Assign the same sharedTransitionTag to elements on different screens.
3. Navigate between screens. The transition will start automatically.

Static

function HomeScreen() {
  const navigation = useNavigation();

  return (
    <View style={styles.container}>
      <Button onPress={() => navigation.navigate('Details')}>
        Go to Details
      </Button>
      <Animated.Image
        source={{ uri: 'https://picsum.photos/id/39/200' }}
        style={{ width: 300, height: 300 }}
        sharedTransitionTag="tag"
      />
    </View>
  );
}

function DetailsScreen() {
  const navigation = useNavigation();

  return (
    <View style={styles.container}>
      <Button onPress={() => navigation.goBack()}>Go back</Button>
      <Animated.Image
        source={{ uri: 'https://picsum.photos/id/39/200' }}
        style={{ width: 100, height: 100 }}
        sharedTransitionTag="tag"
      />
    </View>
  );
}

Dynamic

function HomeScreen() {
  const navigation = useNavigation();

  return (
    <View style={styles.container}>
      <Button onPress={() => navigation.navigate('Details')}>
        Go to Details
      </Button>
      <Animated.Image
        source={{ uri: 'https://picsum.photos/id/39/200' }}
        style={{ width: 300, height: 300 }}
        sharedTransitionTag="tag"
      />
    </View>
  );
}

function DetailsScreen() {
  const navigation = useNavigation();

  return (
    <View style={styles.container}>
      <Button onPress={() => navigation.goBack()}>Go back</Button>
      <Animated.Image
        source={{ uri: 'https://picsum.photos/id/39/200' }}
        style={{ width: 100, height: 100 }}
        sharedTransitionTag="tag"
      />
    </View>
  );
}

sharedTransitionTag is a string that has to be unique in the context of a single screen, but has to match elements between screens. This prop allows Reanimated to identify and animate the elements, similarly to the key property, which tells React which element in the list is which.

Customizing the transition

You can customize the transition by passing a custom SharedTransition configuration via the sharedTransitionStyle prop. Apply the same sharedTransitionStyle to the matching element on the target screen.

Custom transition configuration is not fully finalized and might change in a future release.

New Architecture (Reanimated 4)

On the New Architecture, the default transition animates width, height, originX, originY, transform, backgroundColor, and opacity using withTiming with a 500 ms duration.

Currently customization is more limited due to ongoing development. You can't define fully custom animation functions. Instead, use the SharedTransition builder class to configure duration and spring-based animations:

import { SharedTransition } from 'react-native-reanimated';

// Customize duration and use spring animation
const customTransition = SharedTransition.duration(550).springify();

function HomeScreen() {
  return (