0
# Screen Transitions
1

2
Screen transition system provides gesture-driven screen navigation animations for React Native applications. This system enables smooth, customizable transitions between screens with built-in gesture support and presets for common navigation patterns.
3

4
## Capabilities
5

6
### Starting Screen Transitions
7

8
Initiates a screen transition with gesture handling and animation configuration.
9

10
```typescript { .api }
11
/**
12
 * Starts a screen transition animation with gesture handling
13
 * @param config - Screen transition configuration
14
 */
15
function startScreenTransition(config: ScreenTransitionConfig): void;
16

17
interface ScreenTransitionConfig {
18
  /** Stack identifier for the navigation stack */
19
  stackTag: number;
20
  /** ID or wrapper for the screen below the top screen */
21
  belowTopScreenId: number | ShadowNodeWrapper;
22
  /** ID or wrapper for the top screen being transitioned */
23
  topScreenId: number | ShadowNodeWrapper;
24
  /** Animation configuration for the transition */
25
  screenTransition: AnimatedScreenTransition;
26
  /** Shared value containing gesture event data */
27
  sharedEvent: SharedValue<PanGestureHandlerEventPayload>;
28
  /** Starting position of the gesture */
29
  startingGesturePosition: SharedValue<PanGestureHandlerEventPayload>;
30
  /** Optional callback when animation finishes */
31
  onFinishAnimation?: () => void;
32
  /** Whether the transition was canceled */
33
  isTransitionCanceled: boolean;
34
  /** Type of gesture that triggers go-back behavior */
35
  goBackGesture: GoBackGesture;
36
  /** Screen dimensions for calculations */
37
  screenDimensions: MeasuredDimensions;
38
}
39
```
40

41
**Usage Examples:**
42

43
```typescript
44
import { startScreenTransition, ScreenTransition } from "react-native-reanimated";
45

46
const MyNavigator = () => {
47
  const sharedEvent = useSharedValue<PanGestureHandlerEventPayload>({
48
    x: 0, y: 0, absoluteX: 0, absoluteY: 0,
49
    translationX: 0, translationY: 0,
50
    velocityX: 0, velocityY: 0,
51
  });
52

53
  const startTransition = () => {
54
    startScreenTransition({
55
      stackTag: 1,
56
      belowTopScreenId: previousScreenId,
57
      topScreenId: currentScreenId,
58
      screenTransition: ScreenTransition.SwipeRight,
59
      sharedEvent,
60
      startingGesturePosition: useSharedValue(initialPosition),
61
      goBackGesture: 'swipeRight',
62
      screenDimensions: { width: 375, height: 812, x: 0, y: 0, pageX: 0, pageY: 0 },
63
      isTransitionCanceled: false,
64
    });
65
  };
66
};
67
```
68

69
### Finishing Screen Transitions
70

71
Completes a screen transition with proper cleanup and final animation state.
72

73
```typescript { .api }
74
/**
75
 * Finishes a screen transition with cleanup and final animation state
76
 * @param config - Screen transition configuration
77
 */
78
function finishScreenTransition(config: ScreenTransitionConfig): void;
79
```
80

81
**Usage Examples:**
82

83
```typescript
84
import { finishScreenTransition } from "react-native-reanimated";
85

86
const completeTransition = () => {
87
  finishScreenTransition({
88
    stackTag: 1,
89
    belowTopScreenId: previousScreenId,
90
    topScreenId: currentScreenId,
91
    screenTransition: ScreenTransition.SwipeRight,
92
    sharedEvent,
93
    startingGesturePosition: startPosition,
94
    goBackGesture: 'swipeRight',
95
    screenDimensions: screenDims,
96
    isTransitionCanceled: false,
97
  });
98
};
99
```
100

101
### Screen Transition Presets
102

103
Built-in screen transition animations for common navigation patterns.
104

105
```typescript { .api }
106
const ScreenTransition: {
107
  /** Swipe right transition (iOS-style back navigation) */
108
  SwipeRight: AnimatedScreenTransition;
109
  /** Swipe left transition */
110
  SwipeLeft: AnimatedScreenTransition;
111
  /** Swipe down transition (modal dismiss) */
112
  SwipeDown: AnimatedScreenTransition;
113
  /** Swipe up transition */
114
  SwipeUp: AnimatedScreenTransition;
115
};
116

117
interface AnimatedScreenTransition {
118
  /** Style function for the top screen during transition */
119
  topScreenStyle: (
120
    event: PanGestureHandlerEventPayload,
121
    screenDimensions: MeasuredDimensions
122
  ) => Record<string, unknown>;
123
  /** Style function for the screen below during transition */
124
  belowTopScreenStyle: (
125
    event: PanGestureHandlerEventPayload,
126
    screenDimensions: MeasuredDimensions
127
  ) => Record<string, unknown>;
128
}
129
```
130

131
**Usage Examples:**
132

133
```typescript
134
import { ScreenTransition } from "react-native-reanimated";
135

136
// Using preset transitions
137
const navigationConfig = {
138
  ios: ScreenTransition.SwipeRight,
139
  android: ScreenTransition.SwipeLeft,
140
  modal: ScreenTransition.SwipeDown,
141
};
142

143
// Custom transition
144
const customTransition: AnimatedScreenTransition = {
145
  topScreenStyle: (event, screenSize) => ({
146
    transform: [
147
      { translateX: event.translationX },
148
      { scale: 1 - Math.abs(event.translationX) / screenSize.width * 0.1 }
149
    ],
150
    opacity: 1 - Math.abs(event.translationX) / screenSize.width * 0.3,
151
  }),
152
  belowTopScreenStyle: (event, screenSize) => ({
153
    transform: [
154
      { translateX: (event.translationX - screenSize.width) * 0.3 },
155
    ],
156
  }),
157
};
158
```
159

160
## Types
161

162
### Gesture Types
163

164
```typescript { .api }
165
type GoBackGesture = 
166
  | 'swipeRight'
167
  | 'swipeLeft' 
168
  | 'swipeUp'
169
  | 'swipeDown'
170
  | 'verticalSwipe'
171
  | 'horizontalSwipe'
172
  | 'twoDimensionalSwipe';
173

174
interface PanGestureHandlerEventPayload {
175
  /** Current x position */
176
  x: number;
177
  /** Current y position */
178
  y: number;
179
  /** Absolute x position on screen */
180
  absoluteX: number;
181
  /** Absolute y position on screen */
182
  absoluteY: number;
183
  /** Translation from starting x position */
184
  translationX: number;
185
  /** Translation from starting y position */
186
  translationY: number;
187
  /** Horizontal velocity */
188
  velocityX: number;
189
  /** Vertical velocity */
190
  velocityY: number;
191
}
192
```
193

194
### Screen Dimension Types
195

196
```typescript { .api }
197
interface MeasuredDimensions {
198
  /** X position relative to parent */
199
  x: number;
200
  /** Y position relative to parent */
201
  y: number;
202
  /** Width of the element */
203
  width: number;
204
  /** Height of the element */
205
  height: number;
206
  /** X position relative to screen */
207
  pageX: number;
208
  /** Y position relative to screen */
209
  pageY: number;
210
}
211
```
212

213
### Internal Types
214

215
```typescript { .api }
216
interface ShadowNodeWrapper {
217
  /** Internal shadow node reference */
218
  __hostObjectShadowNodeWrapper: any;
219
}
220

221
type LockAxis = 'x' | 'y' | undefined;
222
```