0
# Layout Components
1

2
Core layout components for structuring navigation screens, managing safe areas, and providing themed backgrounds with proper context integration.
3

4
## Capabilities
5

6
### Screen
7

8
Screen wrapper component that provides navigation context, header integration, and proper layout management for navigation screens.
9

10
```typescript { .api }
11
/**
12
 * Screen wrapper component with navigation context and header integration
13
 * @param props - Screen configuration and content
14
 * @returns React element representing a complete navigation screen
15
 */
16
function Screen(props: {
17
  /** Whether screen is currently focused (required) */
18
  focused: boolean;
19
  /** Whether screen is presented as modal */
20
  modal?: boolean;
21
  /** Navigation object from React Navigation (required) */
22
  navigation: NavigationProp<ParamListBase>;
23
  /** Route object from React Navigation (required) */
24
  route: RouteProp<ParamListBase>;
25
  /** Header component to render (required) */
26
  header: React.ReactNode;
27
  /** Whether to show the header */
28
  headerShown?: boolean;
29
  /** Custom status bar height override */
30
  headerStatusBarHeight?: number;
31
  /** Whether header should be transparent */
32
  headerTransparent?: boolean;
33
  /** Custom screen container styling */
34
  style?: Animated.WithAnimatedValue<StyleProp<ViewStyle>>;
35
  /** Screen content (required) */
36
  children: React.ReactNode;
37
}): React.ReactElement;
38
```
39

40
**Usage Examples:**
41

42
```typescript
43
import { Screen, Header } from "@react-navigation/elements";
44

45
// Basic screen setup
46
function MyScreen({ navigation, route }) {
47
  return (
48
    <Screen
49
      focused={true}
50
      navigation={navigation}
51
      route={route}
52
      header={<Header title="My Screen" />}
53
    >
54
      <View style={{ flex: 1, padding: 20 }}>
55
        <Text>Screen content goes here</Text>
56
      </View>
57
    </Screen>
58
  );
59
}
60

61
// Modal screen
62
function ModalScreen({ navigation, route }) {
63
  return (
64
    <Screen
65
      focused={true}
66
      modal={true}
67
      navigation={navigation}
68
      route={route}
69
      header={
70
        <Header 
71
          title="Modal" 
72
          headerLeft={() => (
73
            <HeaderButton onPress={() => navigation.goBack()}>
74
              <Text>Cancel</Text>
75
            </HeaderButton>
76
          )}
77
        />
78
      }
79
    >
80
      <Text>Modal content</Text>
81
    </Screen>
82
  );
83
}
84

85
// Screen without header
86
function FullScreenView({ navigation, route }) {
87
  return (
88
    <Screen
89
      focused={true}
90
      navigation={navigation}
91
      route={route}
92
      header={<Header title="Hidden" />}
93
      headerShown={false}
94
    >
95
      <Text>Full screen content</Text>
96
    </Screen>
97
  );
98
}
99

100
// Transparent header screen
101
function TransparentHeaderScreen({ navigation, route }) {
102
  return (
103
    <Screen
104
      focused={true}
105
      navigation={navigation}
106
      route={route}
107
      headerTransparent={true}
108
      header={
109
        <Header 
110
          title="Transparent"
111
          headerTransparent={true}
112
          headerBackground={() => (
113
            <View style={{ backgroundColor: 'rgba(255,255,255,0.9)' }} />
114
          )}
115
        />
116
      }
117
    >
118
      <ScrollView>
119
        <Text>Content scrolls under transparent header</Text>
120
      </ScrollView>
121
    </Screen>
122
  );
123
}
124
```
125

126
### Background
127

128
Themed background container component that automatically applies navigation theme colors and provides flexible layout.
129

130
```typescript { .api }
131
/**
132
 * Themed background container with automatic theme color application
133
 * @param props - Background configuration and content
134
 * @returns React element representing a themed background container
135
 */
136
function Background(props: {
137
  /** Custom background styling */
138
  style?: Animated.WithAnimatedValue<StyleProp<ViewStyle>>;
139
  /** Background content (required) */
140
  children: React.ReactNode;
141
} & Omit<ViewProps, 'style'>): React.ReactElement;
142
```
143

144
**Usage Examples:**
145

146
```typescript
147
import { Background } from "@react-navigation/elements";
148

149
// Basic themed background
150
<Background>
151
  <Text>Content with automatic theme background</Text>
152
</Background>
153

154
// Custom styled background
155
<Background 
156
  style={{ 
157
    flex: 1, 
158
    padding: 20,
159
    backgroundColor: '#f5f5f5' 
160
  }}
161
>
162
  <ScrollView>
163
    <Text>Scrollable content</Text>
164
  </ScrollView>
165
</Background>
166

167
// Background with additional props
168
<Background 
169
  style={{ flex: 1 }}
170
  accessibilityRole="main"
171
>
172
  <View>
173
    <Text>Accessible main content area</Text>
174
  </View>
175
</Background>
176
```
177

178
### SafeAreaProviderCompat
179

180
Compatibility wrapper for SafeAreaProvider that handles SSR, test environments, and prevents double-wrapping of safe area contexts.
181

182
```typescript { .api }
183
/**
184
 * Safe area provider compatibility wrapper
185
 * @param props - Provider configuration and content
186
 * @returns React element providing safe area context
187
 */
188
function SafeAreaProviderCompat(props: {
189
  /** Content to wrap with safe area context (required) */
190
  children: React.ReactNode;
191
  /** Custom container styling */
192
  style?: StyleProp<ViewStyle>;
193
}): React.ReactElement;
194

195
/** Initial metrics for safe area calculations */
196
SafeAreaProviderCompat.initialMetrics: {
197
  frame: { x: number; y: number; width: number; height: number };
198
  insets: { top: number; left: number; right: number; bottom: number };
199
} | null;
200
```
201

202
**Usage Examples:**
203

204
```typescript
205
import { SafeAreaProviderCompat } from "@react-navigation/elements";
206

207
// Basic safe area setup
208
function App() {
209
  return (
210
    <SafeAreaProviderCompat>
211
      <NavigationContainer>
212
        <Stack.Navigator>
213
          <Stack.Screen name="Home" component={HomeScreen} />
214
        </Stack.Navigator>
215
      </NavigationContainer>
216
    </SafeAreaProviderCompat>
217
  );
218
}
219

220
// With custom styling
221
<SafeAreaProviderCompat 
222
  style={{ backgroundColor: '#ffffff' }}
223
>
224
  <MyAppContent />
225
</SafeAreaProviderCompat>
226

227
// Accessing initial metrics
228
function MyComponent() {
229
  const initialMetrics = SafeAreaProviderCompat.initialMetrics;
230
  
231
  if (initialMetrics) {
232
    console.log('Safe area insets:', initialMetrics.insets);
233
  }
234
  
235
  return <View>...</View>;
236
}
237
```
238

239
## Layout Patterns
240

241
### Standard Screen Layout
242

243
```typescript
244
function StandardScreen({ navigation, route }) {
245
  return (
246
    <SafeAreaProviderCompat>
247
      <Screen
248
        focused={true}
249
        navigation={navigation}
250
        route={route}
251
        header={<Header title="Standard Layout" />}
252
      >
253
        <Background style={{ flex: 1 }}>
254
          <ScrollView style={{ flex: 1, padding: 16 }}>
255
            <Text>Your content here</Text>
256
          </ScrollView>
257
        </Background>
258
      </Screen>
259
    </SafeAreaProviderCompat>
260
  );
261
}
262
```
263

264
### Modal Layout
265

266
```typescript
267
function ModalLayout({ navigation, route }) {
268
  return (
269
    <Screen
270
      focused={true}
271
      modal={true}
272
      navigation={navigation}
273
      route={route}
274
      header={
275
        <Header 
276
          title="Modal Title"
277
          headerLeft={() => (
278
            <HeaderButton onPress={() => navigation.goBack()}>
279
              <Text>Cancel</Text>
280
            </HeaderButton>
281
          )}
282
        />
283
      }
284
    >
285
      <Background>
286
        <View style={{ padding: 20 }}>
287
          <Text>Modal content</Text>
288
        </View>
289
      </Background>
290
    </Screen>
291
  );
292
}
293
```
294

295
### Full Screen Layout
296

297
```typescript
298
function FullScreenLayout({ navigation, route }) {
299
  return (
300
    <Screen
301
      focused={true}
302
      navigation={navigation}
303
      route={route}
304
      header={<Header title="Hidden" />}
305
      headerShown={false}
306
    >
307
      <View style={{ flex: 1 }}>
308
        <Text>Full screen content without header</Text>
309
      </View>
310
    </Screen>
311
  );
312
}
313
```
314

315
## Context Integration
316

317
The Screen component automatically provides several React contexts:
318

319
- **HeaderHeightContext**: Provides the current header height
320
- **HeaderShownContext**: Indicates whether header is currently shown  
321
- **HeaderBackContext**: Provides back button state and navigation info
322
- **Navigation Context**: Standard React Navigation context integration
323

324
```typescript
325
import { useHeaderHeight } from "@react-navigation/elements";
326

327
function ContentWithHeaderInfo() {
328
  const headerHeight = useHeaderHeight();
329
  
330
  return (
331
    <View style={{ paddingTop: headerHeight }}>
332
      <Text>Content positioned below header</Text>
333
    </View>
334
  );
335
}
336
```
337

338
## Platform Considerations
339

340
### iOS
341
- **Safe Area**: Automatic handling of notch, Dynamic Island, and home indicator
342
- **Status Bar**: Proper status bar style coordination with header
343
- **Modal Presentation**: Native modal presentation styles
344

345
### Android  
346
- **System Bars**: Handles system navigation bar and status bar
347
- **Edge-to-Edge**: Support for edge-to-edge display modes
348
- **Material Design**: Follows Material Design layout principles
349

350
### Web
351
- **Responsive**: Adapts to browser viewport changes
352
- **Accessibility**: Proper semantic structure and ARIA landmarks
353
- **Performance**: Optimized for web rendering and layout shifts