0
# Screen Configuration
1

2
Comprehensive screen configuration options for native stack navigation, including headers, animations, presentations, gestures, and platform-specific behaviors.
3

4
## Capabilities
5

6
### Navigation Options Interface
7

8
The complete interface for configuring screen behavior and appearance.
9

10
```typescript { .api }
11
/**
12
 * Comprehensive configuration options for native stack screens
13
 */
14
interface NativeStackNavigationOptions {
15
  // Basic Options
16
  title?: string;
17
  header?: (props: NativeStackHeaderProps) => React.ReactNode;
18
  headerShown?: boolean;
19
  
20
  // Header Styling
21
  headerStyle?: StyleProp<{ backgroundColor?: string }>;
22
  headerTintColor?: string;
23
  headerTitleAlign?: 'left' | 'center';
24
  headerTitleStyle?: StyleProp<Pick<TextStyle, 'fontFamily' | 'fontSize' | 'fontWeight'> & { color?: string }>;
25
  headerShadowVisible?: boolean;
26
  headerTransparent?: boolean;
27
  headerBlurEffect?: ScreenStackHeaderConfigProps['blurEffect'];
28
  headerBackground?: () => React.ReactNode;
29
  
30
  // Header Components
31
  headerLeft?: (props: NativeStackHeaderLeftProps) => React.ReactNode;
32
  headerRight?: (props: NativeStackHeaderRightProps) => React.ReactNode;
33
  headerTitle?: string | ((props: { children: string; tintColor?: string }) => React.ReactNode);
34
  
35
  // Back Button Configuration
36
  headerBackVisible?: boolean;
37
  headerBackTitle?: string;
38
  headerBackTitleStyle?: StyleProp<{ fontFamily?: string; fontSize?: number }>;
39
  headerBackImageSource?: ImageSourcePropType;
40
  headerBackButtonMenuEnabled?: boolean;
41
  headerBackButtonDisplayMode?: ScreenStackHeaderConfigProps['backButtonDisplayMode'];
42
  
43
  // Large Title (iOS)
44
  headerLargeTitle?: boolean;
45
  headerLargeStyle?: StyleProp<{ backgroundColor?: string }>;
46
  headerLargeTitleShadowVisible?: boolean;
47
  headerLargeTitleStyle?: StyleProp<{
48
    fontFamily?: string;
49
    fontSize?: number;
50
    fontWeight?: string;
51
    color?: string;
52
  }>;
53
  
54
  // Search Bar
55
  headerSearchBarOptions?: SearchBarProps;
56
  
57
  // Screen Presentation
58
  presentation?: 'card' | 'modal' | 'transparentModal' | 'containedModal' | 
59
    'containedTransparentModal' | 'fullScreenModal' | 'formSheet';
60
  
61
  // Animations
62
  animation?: 'default' | 'fade' | 'fade_from_bottom' | 'flip' | 'simple_push' | 
63
    'slide_from_bottom' | 'slide_from_right' | 'slide_from_left' | 
64
    'ios_from_right' | 'ios_from_left' | 'none';
65
  animationDuration?: number;
66
  animationTypeForReplace?: ScreenProps['replaceAnimation'];
67
  animationMatchesGesture?: boolean;
68
  
69
  // Gesture Configuration
70
  gestureEnabled?: boolean;
71
  gestureDirection?: ScreenProps['swipeDirection'];
72
  fullScreenGestureEnabled?: boolean;
73
  fullScreenGestureShadowEnabled?: boolean;
74
  gestureResponseDistance?: ScreenProps['gestureResponseDistance'];
75
  
76
  // Sheet Presentation Options
77
  sheetAllowedDetents?: number[] | 'fitToContents';
78
  sheetInitialDetentIndex?: number | 'last';
79
  sheetExpandsWhenScrolledToEdge?: boolean;
80
  sheetCornerRadius?: number;
81
  sheetGrabberVisible?: boolean;
82
  sheetLargestUndimmedDetentIndex?: number | 'none' | 'last';
83
  sheetElevation?: number;
84
  unstable_sheetFooter?: () => React.ReactNode;
85
  
86
  // Status Bar
87
  statusBarStyle?: ScreenProps['statusBarStyle'];
88
  statusBarAnimation?: ScreenProps['statusBarAnimation'];
89
  statusBarHidden?: boolean;
90
  statusBarBackgroundColor?: string;
91
  statusBarTranslucent?: boolean;
92
  
93
  // Navigation Bar (Android)
94
  navigationBarColor?: string;
95
  navigationBarHidden?: boolean;
96
  navigationBarTranslucent?: boolean;
97
  
98
  // Other Options
99
  contentStyle?: StyleProp<ViewStyle>;
100
  orientation?: ScreenProps['screenOrientation'];
101
  freezeOnBlur?: boolean;
102
  autoHideHomeIndicator?: boolean;
103
  keyboardHandlingEnabled?: boolean;
104
}
105
```
106

107
### Header Configuration
108

109
Configure header appearance and behavior with extensive customization options.
110

111
**Basic Header Options:**
112

113
```typescript
114
// Hide header completely
115
options={{ headerShown: false }}
116

117
// Custom header title
118
options={{ title: "My Screen" }}
119

120
// Custom header styling
121
options={{
122
  headerStyle: { backgroundColor: '#6a51ae' },
123
  headerTintColor: '#fff',
124
  headerTitleStyle: { fontWeight: 'bold' },
125
}}
126

127
// Transparent header
128
options={{
129
  headerTransparent: true,
130
  headerBlurEffect: 'regular', // iOS only
131
}}
132
```
133

134
**Custom Header Components:**
135

136
```typescript
137
// Custom header function
138
options={{
139
  header: ({ navigation, route, options, back }) => (
140
    <CustomHeader 
141
      title={options.title} 
142
      canGoBack={!!back}
143
      onBack={() => navigation.goBack()}
144
    />
145
  ),
146
}}
147

148
// Custom header left/right components
149
options={{
150
  headerLeft: ({ tintColor, canGoBack }) => (
151
    <TouchableOpacity onPress={() => navigation.openDrawer()}>
152
      <Icon name="menu" color={tintColor} />
153
    </TouchableOpacity>
154
  ),
155
  headerRight: ({ tintColor }) => (
156
    <TouchableOpacity onPress={() => navigation.navigate('Settings')}>
157
      <Icon name="settings" color={tintColor} />
158
    </TouchableOpacity>
159
  ),
160
}}
161
```
162

163
### Screen Presentations
164

165
Configure how screens are presented with different modal and transition styles.
166

167
**Presentation Types:**
168

169
```typescript
170
// Standard card presentation (default)
171
options={{ presentation: 'card' }}
172

173
// Modal presentation
174
options={{ presentation: 'modal' }}
175

176
// Transparent modal (previous screen visible)
177
options={{ presentation: 'transparentModal' }}
178

179
// Form sheet (iOS) - bottom sheet style
180
options={{
181
  presentation: 'formSheet',
182
  sheetAllowedDetents: [0.5, 1.0],
183
  sheetInitialDetentIndex: 0,
184
  sheetGrabberVisible: true,
185
}}
186
```
187

188
### Animations and Transitions
189

190
Control screen transition animations and timing.
191

192
**Animation Types:**
193

194
```typescript
195
// Fade transition
196
options={{ animation: 'fade' }}
197

198
// Slide from bottom
199
options={{ 
200
  animation: 'slide_from_bottom',
201
  animationDuration: 300,
202
}}
203

204
// iOS-style slide (Android)
205
options={{ animation: 'ios_from_right' }}
206

207
// No animation
208
options={{ animation: 'none' }}
209

210
// Custom animation matching gestures
211
options={{
212
  animation: 'simple_push',
213
  animationMatchesGesture: true,
214
}}
215
```
216

217
### Gesture Configuration
218

219
Configure swipe gestures and interactions.
220

221
**Gesture Options:**
222

223
```typescript
224
// Disable gestures
225
options={{ gestureEnabled: false }}
226

227
// Vertical dismissal gesture
228
options={{
229
  gestureDirection: 'vertical',
230
  fullScreenGestureEnabled: true,
231
  animation: 'slide_from_bottom',
232
}}
233

234
// Custom gesture response area
235
options={{
236
  fullScreenGestureEnabled: true,
237
  gestureResponseDistance: { start: 25, end: 135, top: 0, bottom: 0 },
238
}}
239
```
240

241
## Usage Examples
242

243
**Complete Screen Configuration:**
244

245
```typescript
246
<Stack.Screen
247
  name="Profile"
248
  component={ProfileScreen}
249
  options={({ route, navigation }) => ({
250
    title: route.params?.name || 'Profile',
251
    headerStyle: { backgroundColor: '#6a51ae' },
252
    headerTintColor: '#fff',
253
    headerRight: ({ tintColor }) => (
254
      <TouchableOpacity 
255
        onPress={() => navigation.navigate('EditProfile')}
256
      >
257
        <Icon name="edit" color={tintColor} />
258
      </TouchableOpacity>
259
    ),
260
    presentation: 'card',
261
    animation: 'slide_from_right',
262
    gestureEnabled: true,
263
    headerBackTitle: 'Back',
264
  })}
265
/>
266
```
267

268
**Modal Screen with Sheet Presentation:**
269

270
```typescript
271
<Stack.Screen
272
  name="Settings"
273
  component={SettingsScreen}
274
  options={{
275
    presentation: 'formSheet',
276
    sheetAllowedDetents: [0.6, 1.0],
277
    sheetInitialDetentIndex: 0,
278
    sheetGrabberVisible: true,
279
    sheetCornerRadius: 16,
280
    headerShown: false,
281
  }}
282
/>
283
```
284

285
## Type Definitions
286

287
```typescript { .api }
288
interface NativeStackHeaderProps {
289
  back?: {
290
    title: string | undefined;
291
    href: string | undefined;
292
  };
293
  options: NativeStackNavigationOptions;
294
  route: Route<string>;
295
  navigation: NativeStackNavigationProp<ParamListBase>;
296
}
297

298
interface NativeStackHeaderLeftProps {
299
  tintColor?: string;
300
  canGoBack?: boolean;
301
  label?: string;
302
  href?: string;
303
}
304

305
interface NativeStackHeaderRightProps {
306
  tintColor?: string;
307
  canGoBack?: boolean;
308
}
309

310
type StyleProp<T> = T | T[] | null | undefined;
311
type ImageSourcePropType = any; // React Native image source
312
```