Skip to content

Commit 2122d6a

Browse files
eds2002eds2002
committed
docs: add screen transitions blog post
Add a community blog post covering react-native-screen-transitions, including setup, an iOS-style card transition, navigation.zoom(), and boundary groups. Add the accompanying demo videos and author metadata. Enable the existing static2dynamic rehype transform for blog posts so the article can use the same Static/Dynamic code example pattern as the docs.
1 parent 8e935f2 commit 2122d6a

7 files changed

Lines changed: 366 additions & 0 deletions

File tree

‎blog/2026-04-27-building-custom-screen-transitions.md‎

Lines changed: 350 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,350 @@
1+
---
2+
title: Building custom screen transitions with react-native-screen-transitions
3+
authors: ed
4+
tags: [community, guide]
5+
---
6+
7+
import Tabs from '@theme/Tabs';
8+
import TabItem from '@theme/TabItem';
9+
10+
There are a few ways to make an app feel more alive, and I'm a big believer that motion is one of them.
11+
12+
Most people already know their OS animations by muscle memory. That's why a custom transition can land so well: used in the right place, it breaks the routine just enough to make a flow feel intentional.
13+
14+
`react-native-screen-transitions` is a React Navigation transition toolkit for flows that need more control over navigation motion. In this article, we'll recreate an iOS-style page transition, then build up to a bounds-driven `navigation.zoom()` flow.
15+
16+
<!--truncate-->
17+
18+
One caveat before we start: this is not a blanket replacement for `@react-navigation/native-stack` or `@react-navigation/stack`. If `native-stack` already does the job, keep using it. If the JS stack already gives you enough control, keep using that too. `react-native-screen-transitions` fits when a specific flow needs more freedom: custom gesture choreography, snap points, bounds-driven motion, or a Reanimated-first transition model.
19+
20+
## Setup
21+
22+
The `react-native-screen-transitions` package contains the transition primitives. In your project directory, run:
23+
24+
```bash npm2yarn
25+
npm install react-native-screen-transitions
26+
```
27+
28+
### Installing peer dependencies
29+
30+
Next, install the necessary peer dependencies used by `react-native-screen-transitions`.
31+
32+
<Tabs groupId='framework' queryString="framework">
33+
<TabItem value='expo' label='Expo' default>
34+
35+
In your project directory, run:
36+
37+
```bash
38+
npx expo install react-native-reanimated react-native-gesture-handler \
39+
@react-navigation/native @react-navigation/native-stack \
40+
@react-navigation/elements react-native-screens \
41+
react-native-safe-area-context
42+
```
43+
44+
This will install versions of these libraries that are compatible with your Expo SDK version.
45+
46+
For the `navigationMaskEnabled` example later in the article, install `@react-native-masked-view/masked-view` too:
47+
48+
```bash
49+
npx expo install @react-native-masked-view/masked-view
50+
```
51+
52+
</TabItem>
53+
<TabItem value='bare' label='Bare React Native'>
54+
55+
In your project directory, run:
56+
57+
```bash npm2yarn
58+
npm install react-native-reanimated react-native-gesture-handler \
59+
@react-navigation/native @react-navigation/native-stack \
60+
@react-navigation/elements react-native-screens \
61+
react-native-safe-area-context
62+
```
63+
64+
If you're on a Mac and developing for iOS, install the pods via [CocoaPods](https://cocoapods.org/) to complete the linking:
65+
66+
```bash
67+
npx pod-install ios
68+
```
69+
70+
For the `navigationMaskEnabled` example later in the article, install `@react-native-masked-view/masked-view` too:
71+
72+
```bash npm2yarn
73+
npm install @react-native-masked-view/masked-view
74+
```
75+
76+
</TabItem>
77+
</Tabs>
78+
79+
## Recreating the iOS page transition
80+
81+
<div className="device-frame">
82+
<video playsInline autoPlay muted loop>
83+
<source src="/assets/blog/screen-transitions/ios-reference.mp4" />
84+
</video>
85+
</div>
86+
87+
Let's dissect the native iOS page animation and mimic it closely:
88+
89+
- the incoming screen slides in from the right
90+
- the screen underneath shifts slightly left
91+
- optionally, we can round the corners of the page, and on newer iOS versions that can move closer to a squircle look
92+
93+
## Start with a Blank Stack
94+
95+
Blank Stack is the navigator that ships with `react-native-screen-transitions`. It comes with no built-in animations, so every transition is yours to define. That's exactly what we want here.
96+
97+
```tsx static2dynamic
98+
import { createBlankStackNavigator } from 'react-native-screen-transitions/blank-stack';
99+
100+
const RootStack = createBlankStackNavigator({
101+
screens: {
102+
Home: HomeScreen,
103+
Detail: DetailScreen,
104+
},
105+
});
106+
```
107+
108+
## Define the transition
109+
110+
To define a transition, we configure two things: how the gesture behaves, and how the screen animates.
111+
112+
`transitionSpec` controls the spring configuration for opening and closing. `screenStyleInterpolator` is the function that returns the animated styles for the transition based on values like progress and screen layout. For this example, we'll keep it simple and drive everything from the root-level progress helper.
113+
114+
```tsx
115+
import { interpolate } from 'react-native-reanimated';
116+
import Transition, {
117+
type ScreenTransitionConfig,
118+
} from 'react-native-screen-transitions';
119+
120+
const iosCardStackTransition: ScreenTransitionConfig = {
121+
gestureEnabled: true,
122+
gestureDirection: 'horizontal',
123+
transitionSpec: {
124+
open: Transition.Specs.DefaultSpec,
125+
close: Transition.Specs.DefaultSpec,
126+
},
127+
screenStyleInterpolator: ({ active, current, progress }) => {
128+
'worklet';
129+
130+
const width = current.layouts.screen.width;
131+
const translateX = interpolate(
132+
progress,
133+
[0, 1, 2],
134+
[width, 0, -width * 0.3],
135+
'clamp'
136+
);
137+
138+
return {
139+
content: {
140+
borderRadius: active.settled ? 0 : DEVICE_CORNER_RADIUS,
141+
borderCurve: active.settled ? 'continuous' : 'circular',
142+
overflow: 'hidden',
143+
transform: [{ translateX }],
144+
},
145+
backdrop: {
146+
backgroundColor: 'rgba(0,0,0,1)',
147+
opacity: interpolate(active.progress, [0, 1], [0, 0.1], 'clamp'),
148+
},
149+
};
150+
},
151+
};
152+
```
153+
154+
Then apply that config to the stack:
155+
156+
```tsx static2dynamic
157+
const RootStack = createBlankStackNavigator({
158+
screens: {
159+
Home: HomeScreen,
160+
Detail: {
161+
screen: DetailScreen,
162+
options: iosCardStackTransition,
163+
},
164+
},
165+
});
166+
```
167+
168+
<div className="device-frame">
169+
<video playsInline autoPlay muted loop>
170+
<source src="/assets/blog/screen-transitions/ios-card-transition.mp4" />
171+
</video>
172+
</div>
173+
174+
And we're set: a close replica of the iOS page animation.
175+
176+
The interesting bit is `screenStyleInterpolator`. We're using one root-level `progress` value to describe both sides of the transition:
177+
178+
- When `progress` goes from `0 -> 1`: the incoming screen moves from `width` to `0`
179+
- When `progress` goes from `1 -> 2`: the previous screen continues from `0` to `-width * 0.3`
180+
- `current.layouts.screen.width` gives us the full distance to work with
181+
- `transform: [{ translateX }]` is applied on `content`, so the whole screen moves as one unit
182+
- `borderRadius: active.settled ? 0 : DEVICE_CORNER_RADIUS` only rounds the screen while it is moving, then lets it settle back to full-bleed
183+
- `borderCurve` helps the corners read closer to the system look while the card is in motion
184+
- the `backdrop` fade adds just a little depth under the active screen
185+
186+
## Why not just use JS stack?
187+
188+
JS stack already does this, so what's the point?
189+
190+
For the example above, nothing. JS stack does this well, and if that's all you need, use it.
191+
192+
Where `react-native-screen-transitions` starts to pay off is when the transition needs to know about geometry: the position and size of a specific component on one screen, animating to a specific component on another. That's not something JS stack expresses cleanly, and it's what makes the next example possible.
193+
194+
## navigation.zoom()
195+
196+
<div className="device-frame">
197+
<video playsInline autoPlay muted loop>
198+
<source src="/assets/blog/screen-transitions/navigation-zoom.mp4" />
199+
</video>
200+
</div>
201+
202+
One thing I'm really proud to announce with v3.4 is `navigation.zoom()`.
203+
204+
`navigation.zoom()` is a bounds-driven helper for recreating that navigation zoom handoff between a source element and a destination screen. It works by measuring component A and component B with the Bounds API, then animating between them. This isn't a traditional shared-element system, so if that's what you need, I'd wait for Reanimated's version to mature.
205+
206+
Let's start with the source screen. In a realistic flow, the card already knows which item it represents, so use that item's id as the boundary id and pass it through navigation.
207+
208+
```tsx
209+
function FeedCard({ item, navigation }) {
210+
return (
211+
<Transition.Boundary.Trigger
212+
id={item.id}
213+
onPress={() => {
214+
navigation.navigate('Detail', { id: item.id });
215+
}}
216+
>
217+
<Image source={item.image} style={styles.card} />
218+
</Transition.Boundary.Trigger>
219+
);
220+
}
221+
```
222+
223+
On the destination screen, use the same `id` from `route.params`. You don't have to define a `Transition.Boundary.View` on the destination, but if you want the destination to resize itself to match component A's bounds, you should.
224+
225+
```tsx
226+
function DetailScreen({ route }) {
227+
const item = getItem(route.params.id);
228+
229+
return (
230+
<View style={styles.screen}>
231+
<Transition.Boundary.View id={item.id} style={styles.hero}>
232+
<Image source={item.image} style={styles.hero} />
233+
</Transition.Boundary.View>
234+
</View>
235+
);
236+
}
237+
```
238+
239+
Now orchestrate the animation. `options` receives `route`, so we can derive the same `id` there and pass it into the bounds helper:
240+
241+
```tsx static2dynamic
242+
const RootStack = createBlankStackNavigator({
243+
screens: {
244+
Feed: FeedScreen,
245+
Detail: {
246+
screen: DetailScreen,
247+
options: ({ route }) => {
248+
const zoomId = route.params.id;
249+
250+
return {
251+
navigationMaskEnabled: Platform.OS === 'ios',
252+
gestureEnabled: true,
253+
gestureDirection: ['vertical', 'vertical-inverted', 'horizontal'],
254+
gestureDrivesProgress: false,
255+
transitionSpec: {
256+
open: Transition.Specs.DefaultSpec,
257+
close: Transition.Specs.FlingSpec,
258+
},
259+
screenStyleInterpolator: ({ bounds }) => {
260+
'worklet';
261+
262+
return bounds({ id: zoomId }).navigation.zoom({
263+
target: 'bound',
264+
});
265+
},
266+
};
267+
},
268+
},
269+
},
270+
});
271+
```
272+
273+
A few choices here are worth calling out.
274+
275+
`navigationMaskEnabled` requires `@react-native-masked-view/masked-view`. I keep the platform guard because animating layout properties on the mask element tends to hold up much better on iOS than on Android.
276+
277+
`gestureDrivesProgress: false` means the drag does not directly scrub the stack's main transition progress. The gesture still updates live drag values and still participates in the dismiss decision on release, but the zoom helper stays in control of the interaction instead of behaving like a normal interactive pop.
278+
279+
`close: Transition.Specs.FlingSpec` turns `overshootClamping` off and uses a looser spring, so a release or fling feels more natural on the way out.
280+
281+
### Taking this further with boundary groups
282+
283+
The example above works well when you have one obvious source and one obvious destination. A gallery is more interesting. You might have a masonry grid on the index screen, then a paged detail screen where the user can swipe between images before closing.
284+
285+
<div className="device-frame">
286+
<video playsInline autoPlay muted loop>
287+
<source src="/assets/blog/screen-transitions/boundary-groups.mp4" />
288+
</video>
289+
</div>
290+
291+
This is where the boundary `group` prop becomes useful. Think of `group` as a namespace for a family of related bounds. The `id` still chooses the specific item, but the `group` tells the system which collection that item belongs to.
292+
293+
Start by defining a stable group and a mutable value for the active item:
294+
295+
```tsx
296+
export const GALLERY_GROUP = 'gallery';
297+
export const activeGalleryId = makeMutable(GALLERY_ITEMS[0].id);
298+
```
299+
300+
On the source screen, every thumbnail uses its own `id`, but they all share the same `group`:
301+
302+
```tsx
303+
<Transition.Boundary.Trigger
304+
id={item.id}
305+
group={GALLERY_GROUP}
306+
onPress={() => {
307+
activeGalleryId.set(item.id);
308+
navigation.navigate('Detail', { id: item.id });
309+
}}
310+
>
311+
<Image source={{ uri: item.uri }} style={styles.image} />
312+
</Transition.Boundary.Trigger>
313+
```
314+
315+
On the destination screen, the matching image uses the same `id` and the same `group`:
316+
317+
```tsx
318+
<Transition.Boundary.View
319+
id={item.id}
320+
group={GALLERY_GROUP}
321+
style={{ width: imageWidth, height: imageHeight }}
322+
>
323+
<Image source={{ uri: item.uri }} style={styles.image} />
324+
</Transition.Boundary.View>
325+
```
326+
327+
Then the transition asks bounds for both values:
328+
329+
```tsx
330+
const id = activeGalleryId.get();
331+
332+
return bounds({
333+
id,
334+
group: GALLERY_GROUP,
335+
}).navigation.zoom({ target: 'bound' });
336+
```
337+
338+
Groups are useful when the active item can change while the destination stays mounted. The mutable `activeGalleryId` keeps track of the current active id, so when bounds need a fresh measurement, for example before a drag or dismiss, the system knows which element to remeasure.
339+
340+
The gallery example also updates `activeGalleryId` when the horizontal detail list settles on a new page. That way, if the user opens one image, swipes to another, and then closes the screen, the transition returns to the image they are actually looking at instead of the one they originally opened.
341+
342+
And that's the whole thing: SwiftUI's `navigation.zoom()` look in pure JS.
343+
344+
The full source for both examples lives [here](https://github.com/eds2002/react-native-screen-transitions) if you want to poke at it.
345+
346+
## What's next for Screen Transitions
347+
348+
I've been quietly working on the next wave of improvements: moving the architecture over to Reanimated 4, Gesture Handler v3, and React 19's new Activity component. Pinch-in and pinch-out transitions are also in progress, so there should be a few exciting changes landing soon.
349+
350+
Thanks for all the support on Screen Transitions. It's honestly a dream package for me, and I'm excited that other people seem to share the excitement. If you build something with it, I'd love to see it!

‎blog/authors.yml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,3 +47,12 @@ oskar:
4747
socials:
4848
x: o_kwasniewski
4949
github: okwasniewsk
50+
51+
ed:
52+
name: Ed
53+
url: https://github.com/eds2002
54+
image_url: https://github.com/eds2002.png
55+
title: React Native Screen Transitions
56+
socials:
57+
x: trpfsu
58+
github: eds2002

‎docusaurus.config.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -186,6 +186,13 @@ const config: Config = {
186186
},
187187
blog: {
188188
remarkPlugins: [[remarkNpm2Yarn, { sync: true }]],
189+
rehypePlugins: [
190+
[
191+
rehypeCodeblockMeta,
192+
{ match: { snack: true, lang: true, tabs: true } },
193+
],
194+
rehypeStaticToDynamic,
195+
],
189196
},
190197
pages: {
191198
remarkPlugins: [[remarkNpm2Yarn, { sync: true }]],

‎static/assets/blog/screen-transitions/boundary-groups.mp4‎

3.27 MB
Binary file not shown.

‎static/assets/blog/screen-transitions/ios-card-transition.mp4‎

52.4 KB
Binary file not shown.

‎static/assets/blog/screen-transitions/ios-reference.mp4‎

42.8 KB
Binary file not shown.

‎static/assets/blog/screen-transitions/navigation-zoom.mp4‎

1.46 MB
Binary file not shown.

0 commit comments

Comments
 (0)