Screens and boundaries
Shared Element Transitions run between screens. A boundary tells Reanimated where a screen is: you put a boundary around the content of each screen, and you tell each boundary if its screen is the one that the user sees. When the active boundary changes, Reanimated runs a transition between the views with the same sharedTransitionTag in the old and the new boundary.
With boundaries, Shared Element Transitions work with any navigation setup: stacks, tabs, nested navigators, modals, or screens that you show without a navigator.
SharedTransitionBoundary
The component that marks a screen for Shared Element Transitions.
Reference
import { useIsFocused } from '@react-navigation/native';
import Animated, { SharedTransitionBoundary } from 'react-native-reanimated';
function DetailsScreen() {
const isFocused = useIsFocused();
return (
<SharedTransitionBoundary isActive={isFocused}>
<Animated.View sharedTransitionTag="photo" />
{/* the rest of the screen */}
</SharedTransitionBoundary>
);
}


Type definitions
interface SharedTransitionBoundaryProps {
isActive: boolean;
children?: ReactNode;
}
Arguments
isActive
A boolean that tells if the user sees this screen. With React Navigation, use the value of useIsFocused(). When the active boundary changes, the transition starts.
children Optional
The content of the screen. SharedTransitionBoundary does not change the layout: it renders with display: 'contents'.
Example
Usage with navigation
One boundary should contain all shared views of its screen, so wrap whole screens, not single views. Set isActive to true only while the screen is focused.
Use @react-navigation/core 7.16.0 or newer, which @react-navigation/native 7.1.32 and newer require. In older versions, useIsFocused() changes one update after a screen is removed, so on Android the transition back to the previous screen sometimes does not run.
You can wrap screens in three ways:
- All screens of a navigator, with
screenLayout. Use it when the screens of the navigator are normal screens, not other navigators. - One screen component, with a higher-order component. Use it when only some screens have shared views, or when the screens of a navigator are other navigators.
- The content of a screen, by hand. Use it when a screen needs its own
isActivevalue, for example with a React NativeModal.
All screens of a navigator
The screenLayout prop of a React Navigation navigator wraps each of its screens:
import { useIsFocused } from '@react-navigation/native';
import { SharedTransitionBoundary } from 'react-native-reanimated';
function ScreenBoundary({ children }: { children: React.ReactNode }) {
const isFocused = useIsFocused();
return (
<SharedTransitionBoundary isActive={isFocused}>
{children}
</SharedTransitionBoundary>
);
}
const Stack = createNativeStackNavigator();
function App() {
return (
<Stack.Navigator
screenLayout={({ children }) => <ScreenBoundary>{children}</ScreenBoundary>}>
<Stack.Screen name="List" component={ListScreen} />
<Stack.Screen name="Details" component={DetailsScreen} />
</Stack.Navigator>
);
}
screenLayout works the same way with tabs and other navigators. To wrap only some screens, use the layout prop of each Stack.Screen.
One screen component
A small higher-order component wraps one screen:
function withSharedTransitionBoundary<P extends object>(
Screen: React.ComponentType<P>
) {
return function ScreenWithBoundary(props: P) {
const isFocused = useIsFocused();
return (
<SharedTransitionBoundary isActive={isFocused}>
<Screen {...props} />
</SharedTransitionBoundary>
);
};
}
const List = withSharedTransitionBoundary(ListScreen);
const Details = withSharedTransitionBoundary(DetailsScreen);
function App() {
return (
<Stack.Navigator>
<Stack.Screen name="List" component={List} />
<Stack.Screen name="Details" component={Details} />
</Stack.Navigator>
);
}
Create each wrapped screen outside of components, as in the example. A new component on each render mounts the screen again.
The content of a screen
You can also put the boundary in the screen itself. Make it the outer element of the screen:
function DetailsScreen() {
const isFocused = useIsFocused();
return (
<SharedTransitionBoundary isActive={isFocused}>
<Header />
<Animated.View sharedTransitionTag="photo" style={styles.photo} />
<Description />
</SharedTransitionBoundary>
);
}
Nested navigators
Reanimated looks for the active boundary from the root of the app, and it does not look for other boundaries inside an active boundary. A boundary around a navigator stays active while any of its screens shows, so it hides the boundaries of these screens.
For this reason, do not use screenLayout on a navigator whose screens are other navigators. Use it on the inner navigators, and wrap the other screens one by one:
function HomeStack() {
return (
<Stack.Navigator
screenLayout={({ children }) => <ScreenBoundary>{children}</ScreenBoundary>}>
<Stack.Screen name="Feed" component={FeedScreen} />
<Stack.Screen name="Post" component={PostScreen} />
</Stack.Navigator>
);
}
const Settings = withSharedTransitionBoundary(SettingsScreen);
function App() {
return (
// no screenLayout here: HomeStack is a navigator
<Tab.Navigator>
<Tab.Screen name="HomeStack" component={HomeStack} />
<Tab.Screen name="Settings" component={Settings} />
</Tab.Navigator>
);
}
Without a navigator
You do not need a navigator. Set isActive from your own state:
function Gallery() {
const [selected, setSelected] = useState<string | null>(null);
return (
<>
<SharedTransitionBoundary isActive={selected === null}>
<Grid onSelect={setSelected} />
</SharedTransitionBoundary>
{selected !== null && (
<SharedTransitionBoundary isActive>
<Details id={selected} onClose={() => setSelected(null)} />
</SharedTransitionBoundary>
)}
</>
);
}
Expo Router
With Expo Router, import useIsFocused from expo-router. Put the boundaries in the layouts of the stacks that show your screens:
// app/(tabs)/gallery/_layout.tsx
import { Stack, useIsFocused } from 'expo-router';
import { SharedTransitionBoundary } from 'react-native-reanimated';
function ScreenBoundary({ children }: { children: React.ReactNode }) {
const isFocused = useIsFocused();
return (
<SharedTransitionBoundary isActive={isFocused}>
{children}
</SharedTransitionBoundary>
);
}
export default function GalleryLayout() {
return (
<Stack
screenLayout={({ children }) => <ScreenBoundary>{children}</ScreenBoundary>}>
<Stack.Screen name="index" />
<Stack.Screen name="[id]" />
</Stack>
);
}
- Do not use
screenLayoutin a layout whose routes are other navigators, for example in the root_layout.tsxthat shows a(tabs)group, or in the layout of the(tabs)group. See Nested navigators. - A route that the root stack shows as a modal, for example
photo/[id]withpresentation: 'modal', is a screen of the root stack. Put its boundary in the content of the screen.
Modals
During a transition to or from a modal, the moving view shows above the modal.
Native stack modals
A screen that a native stack presents as a modal is a normal screen of the navigator. Wrap it in the same way as the other screens:
<Stack.Navigator
screenLayout={({ children }) => <ScreenBoundary>{children}</ScreenBoundary>}>
<Stack.Screen name="List" component={ListScreen} />
<Stack.Screen
name="Photo"
component={PhotoScreen}
options={{ presentation: 'formSheet' }}
/>
</Stack.Navigator>
On iOS, when the user closes a sheet with a swipe, the view follows the swipe. If the user cancels the swipe, the view goes back to the sheet.
React Native Modal
A React Native Modal is not a screen, so useIsFocused() does not change when it opens. Set isActive of both boundaries from the state of the modal:
<SharedTransitionBoundary isActive={isFocused && !isModalVisible}>
{/* screen content */}
</SharedTransitionBoundary>
<Modal visible={isModalVisible}>
<SharedTransitionBoundary isActive={isModalVisible}>
{/* modal content */}
</SharedTransitionBoundary>
</Modal>
On Android, a view does not move between the screen and a Modal. See Modals and windows.
Remarks
- Reanimated runs a transition only between two boundaries. A view outside of all boundaries does not take part.
- Only one boundary should be active at a time. If more boundaries are active, Reanimated uses the one that React renders last.
- A shared view that mounts under an inactive boundary shows as usual, for example in a list under a sheet. Reanimated hides it only when the active boundary shows a view with the same tag, or when a transition moves that tag.
- When a new boundary becomes active during a transition, for example when the user goes back before the transition ends, the view turns and moves to its match in the new boundary. If the new boundary has no match, the transition stops and the views show in their own places at once.
Platform compatibility
| Android | iOS | Web |
|---|---|---|
| ✅ | ✅ | ❌ |