0
# Header Components
1

2
Components for configuring native navigation headers with platform-specific styling and behavior. These components provide comprehensive header customization while maintaining native performance and appearance.
3

4
## Core Imports
5

6
```typescript
7
import {
8
  ScreenStackHeaderConfig,
9
  ScreenStackHeaderSubview,
10
  ScreenStackHeaderLeftView,
11
  ScreenStackHeaderCenterView,
12
  ScreenStackHeaderRightView,
13
  ScreenStackHeaderBackButtonImage,
14
  ScreenStackHeaderSearchBarView,
15
  SearchBar
16
} from "react-native-screens";
17
```
18

19
## Capabilities
20

21
### ScreenStackHeaderConfig
22

23
Main configuration component for native navigation headers. Provides comprehensive customization options while maintaining platform-native appearance and behavior.
24

25
```typescript { .api }
26
/**
27
 * Configuration component for native navigation headers
28
 */
29
function ScreenStackHeaderConfig(props: ScreenStackHeaderConfigProps): JSX.Element;
30

31
interface ScreenStackHeaderConfigProps {
32
  /** Header title text */
33
  title?: string;
34
  
35
  /** Title font family */
36
  titleFontFamily?: string;
37
  
38
  /** Title font size */
39
  titleFontSize?: number;
40
  
41
  /** Title font weight */
42
  titleFontWeight?: 'normal' | 'bold' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900';
43
  
44
  /** Title color */
45
  titleColor?: ColorValue;
46
  
47
  /** Whether header is hidden */
48
  hidden?: boolean;
49
  
50
  /** Header background color */
51
  backgroundColor?: ColorValue;
52
  
53
  /** Header blur effect (iOS) */
54
  blurEffect?: BlurEffectTypes;
55
  
56
  /** Large title display (iOS) */
57
  largeTitle?: boolean;
58
  
59
  /** Large title font family (iOS) */
60
  largeTitleFontFamily?: string;
61
  
62
  /** Large title font size (iOS) */
63
  largeTitleFontSize?: number;
64
  
65
  /** Large title font weight (iOS) */
66
  largeTitleFontWeight?: 'normal' | 'bold' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900';
67
  
68
  /** Large title color (iOS) */
69
  largeTitleColor?: ColorValue;
70
  
71
  /** Large title background color (iOS) */
72
  largeTitleBackgroundColor?: ColorValue;
73
  
74
  /** Large title hide shadow (iOS) */
75
  largeTitleHideShadow?: boolean;
76
  
77
  /** Back button title (iOS) */
78
  backTitle?: string;
79
  
80
  /** Back button font family (iOS) */
81
  backTitleFontFamily?: string;
82
  
83
  /** Back button font size (iOS) */
84
  backTitleFontSize?: number;
85
  
86
  /** Back button display mode (iOS) */
87
  backButtonDisplayMode?: BackButtonDisplayMode;
88
  
89
  /** Back button tint color */
90
  backButtonColor?: ColorValue;
91
  
92
  /** Whether back button is hidden */
93
  hideBackButton?: boolean;
94
  
95
  /** Whether shadow is hidden */
96
  hideShadow?: boolean;
97
  
98
  /** Translucent header appearance */
99
  translucent?: boolean;
100
  
101
  /** Direction for RTL support */
102
  direction?: 'rtl' | 'ltr';
103
  
104
  /** Color for header items */
105
  color?: ColorValue;
106
  
107
  /** Disable back button menu (iOS) */
108
  disableBackButtonMenu?: boolean;
109
  
110
  /** Callback when back button is pressed */
111
  onBackButtonPress?: () => void;
112
}
113
```
114

115
**Usage Example:**
116

117
```typescript
118
import React from 'react';
119
import { Screen, ScreenStackHeaderConfig } from 'react-native-screens';
120
import { View, Text } from 'react-native';
121

122
function HeaderScreen() {
123
  return (
124
    <Screen>
125
      <ScreenStackHeaderConfig
126
        title="My Screen"
127
        backgroundColor="#007AFF"
128
        titleColor="white"
129
        backButtonColor="white"
130
        largeTitle={true}
131
        hideShadow={false}
132
      />
133
      <View>
134
        <Text>Screen with custom header</Text>
135
      </View>
136
    </Screen>
137
  );
138
}
139
```
140

141
### ScreenStackHeaderSubview
142

143
Base component for header subviews that provides common functionality for all header customization components.
144

145
```typescript { .api }
146
/**
147
 * Base component for header subviews
148
 */
149
function ScreenStackHeaderSubview(props: ViewProps): JSX.Element;
150
```
151

152
### ScreenStackHeaderLeftView
153

154
Component for customizing the left side of the navigation header, typically used for custom back buttons or additional navigation actions.
155

156
```typescript { .api }
157
/**
158
 * Component for customizing the left side of the header
159
 */
160
function ScreenStackHeaderLeftView(props: ViewProps): JSX.Element;
161
```
162

163
**Usage Example:**
164

165
```typescript
166
import React from 'react';
167
import {
168
  Screen,
169
  ScreenStackHeaderConfig,
170
  ScreenStackHeaderLeftView
171
} from 'react-native-screens';
172
import { TouchableOpacity, Text } from 'react-native';
173

174
function CustomLeftHeaderScreen() {
175
  return (
176
    <Screen>
177
      <ScreenStackHeaderConfig title="Custom Header">
178
        <ScreenStackHeaderLeftView>
179
          <TouchableOpacity onPress={() => console.log('Custom back')}>
180
            <Text style={{ color: '#007AFF', fontSize: 16 }}>Cancel</Text>
181
          </TouchableOpacity>
182
        </ScreenStackHeaderLeftView>
183
      </ScreenStackHeaderConfig>
184
    </Screen>
185
  );
186
}
187
```
188

189
### ScreenStackHeaderCenterView
190

191
Component for customizing the center area of the navigation header, allowing for custom title layouts or branding.
192

193
```typescript { .api }
194
/**
195
 * Component for customizing the center area of the header
196
 */
197
function ScreenStackHeaderCenterView(props: ViewProps): JSX.Element;
198
```
199

200
**Usage Example:**
201

202
```typescript
203
import React from 'react';
204
import {
205
  Screen,
206
  ScreenStackHeaderConfig,
207
  ScreenStackHeaderCenterView
208
} from 'react-native-screens';
209
import { Image, View } from 'react-native';
210

211
function CustomCenterHeaderScreen() {
212
  return (
213
    <Screen>
214
      <ScreenStackHeaderConfig>
215
        <ScreenStackHeaderCenterView>
216
          <View style={{ flexDirection: 'row', alignItems: 'center' }}>
217
            <Image 
218
              source={require('./logo.png')} 
219
              style={{ width: 24, height: 24, marginRight: 8 }}
220
            />
221
            <Text style={{ fontSize: 18, fontWeight: 'bold' }}>MyApp</Text>
222
          </View>
223
        </ScreenStackHeaderCenterView>
224
      </ScreenStackHeaderConfig>
225
    </Screen>
226
  );
227
}
228
```
229

230
### ScreenStackHeaderRightView
231

232
Component for customizing the right side of the navigation header, commonly used for action buttons or secondary navigation.
233

234
```typescript { .api }
235
/**
236
 * Component for customizing the right side of the header
237
 */
238
function ScreenStackHeaderRightView(props: ViewProps): JSX.Element;
239
```
240

241
**Usage Example:**
242

243
```typescript
244
import React from 'react';
245
import {
246
  Screen,
247
  ScreenStackHeaderConfig,
248
  ScreenStackHeaderRightView
249
} from 'react-native-screens';
250
import { TouchableOpacity, Text } from 'react-native';
251

252
function CustomRightHeaderScreen() {
253
  return (
254
    <Screen>
255
      <ScreenStackHeaderConfig title="Settings">
256
        <ScreenStackHeaderRightView>
257
          <TouchableOpacity onPress={() => console.log('Save pressed')}>
258
            <Text style={{ color: '#007AFF', fontSize: 16, fontWeight: 'bold' }}>
259
              Save
260
            </Text>
261
          </TouchableOpacity>
262
        </ScreenStackHeaderRightView>
263
      </ScreenStackHeaderConfig>
264
    </Screen>
265
  );
266
}
267
```
268

269
### ScreenStackHeaderBackButtonImage
270

271
Component for customizing the back button image in the navigation header.
272

273
```typescript { .api }
274
/**
275
 * Component for customizing the back button image
276
 */
277
function ScreenStackHeaderBackButtonImage(props: ViewProps): JSX.Element;
278
```
279

280
**Usage Example:**
281

282
```typescript
283
import React from 'react';
284
import {
285
  Screen,
286
  ScreenStackHeaderConfig,
287
  ScreenStackHeaderBackButtonImage
288
} from 'react-native-screens';
289
import { Image } from 'react-native';
290

291
function CustomBackButtonScreen() {
292
  return (
293
    <Screen>
294
      <ScreenStackHeaderConfig title="Custom Back">
295
        <ScreenStackHeaderBackButtonImage>
296
          <Image 
297
            source={require('./custom-back-icon.png')} 
298
            style={{ width: 24, height: 24 }}
299
          />
300
        </ScreenStackHeaderBackButtonImage>
301
      </ScreenStackHeaderConfig>
302
    </Screen>
303
  );
304
}
305
```
306

307
### ScreenStackHeaderSearchBarView
308

309
Component for integrating a search bar into the navigation header. Provides native search functionality with platform-appropriate styling.
310

311
```typescript { .api }
312
/**
313
 * Component for integrating search bar into the header
314
 */
315
function ScreenStackHeaderSearchBarView(props: ViewProps): JSX.Element;
316
```
317

318
**Usage Example:**
319

320
```typescript
321
import React from 'react';
322
import {
323
  Screen,
324
  ScreenStackHeaderConfig,
325
  ScreenStackHeaderSearchBarView,
326
  SearchBar
327
} from 'react-native-screens';
328

329
function SearchHeaderScreen() {
330
  return (
331
    <Screen>
332
      <ScreenStackHeaderConfig title="Search">
333
        <ScreenStackHeaderSearchBarView>
334
          <SearchBar
335
            placeholder="Search items..."
336
            onChangeText={(text) => console.log('Search:', text)}
337
          />
338
        </ScreenStackHeaderSearchBarView>
339
      </ScreenStackHeaderConfig>
340
    </Screen>
341
  );
342
}
343
```
344

345
### SearchBar
346

347
Native search bar component that provides platform-native search functionality for iOS and Android.
348

349
```typescript { .api }
350
/**
351
 * Native search bar component for iOS and Android
352
 */
353
function SearchBar(props: SearchBarProps): JSX.Element;
354

355
interface SearchBarProps {
356
  /** Placeholder text */
357
  placeholder?: string;
358
  
359
  /** Search bar placement */
360
  placement?: SearchBarPlacement;
361
  
362
  /** Whether search bar is obscured during presentation */
363
  obscureBackground?: boolean;
364
  
365
  /** Whether search bar hides navigation bar during search */
366
  hideNavigationBar?: boolean;
367
  
368
  /** Whether search bar hides when scrolling */
369
  hideWhenScrolling?: boolean;
370
  
371
  /** Auto-capitalize behavior */
372
  autoCapitalize?: 'none' | 'words' | 'sentences' | 'characters';
373
  
374
  /** Input accessory view (iOS) */
375
  inputType?: 'text' | 'phone' | 'number' | 'email';
376
  
377
  /** Callback when text changes */
378
  onChangeText?: (text: string) => void;
379
  
380
  /** Callback when search button is pressed */
381
  onSearchButtonPress?: (event: NativeSyntheticEvent<{ text: string }>) => void;
382
  
383
  /** Callback when cancel button is pressed */
384
  onCancelButtonPress?: (event: NativeSyntheticEvent<{}>) => void;
385
  
386
  /** Callback when search bar gains focus */
387
  onFocus?: (event: NativeSyntheticEvent<{}>) => void;
388
  
389
  /** Callback when search bar loses focus */
390
  onBlur?: (event: NativeSyntheticEvent<{}>) => void;
391
  
392
  /** Text color */
393
  textColor?: ColorValue;
394
  
395
  /** Tint color */
396
  tintColor?: ColorValue;
397
  
398
  /** Bar tint color (iOS) */
399
  barTintColor?: ColorValue;
400
  
401
  /** Search bar style (iOS) */
402
  searchBarStyle?: 'default' | 'prominent' | 'minimal';
403
}
404

405
// Ref commands for SearchBar
406
interface SearchBarCommands {
407
  /** Focus the search bar */
408
  focus(): void;
409
  
410
  /** Blur the search bar */
411
  blur(): void;
412
  
413
  /** Clear search text */
414
  clearText(): void;
415
  
416
  /** Set search text programmatically */
417
  setText(text: string): void;
418
  
419
  /** Toggle cancel button visibility */
420
  toggleCancelButton(show: boolean): void;
421
  
422
  /** Cancel current search */
423
  cancelSearch(): void;
424
}
425
```
426

427
**Usage Example:**
428

429
```typescript
430
import React, { useRef, useState } from 'react';
431
import { SearchBar, SearchBarCommands } from 'react-native-screens';
432

433
function SearchScreen() {
434
  const searchRef = useRef<SearchBarCommands>(null);
435
  const [searchText, setSearchText] = useState('');
436

437
  const handleSearch = () => {
438
    console.log('Searching for:', searchText);
439
  };
440

441
  const clearSearch = () => {
442
    searchRef.current?.clearText();
443
    setSearchText('');
444
  };
445

446
  return (
447
    <SearchBar
448
      ref={searchRef}
449
      placeholder="Search products..."
450
      placement="stacked"
451
      autoCapitalize="none"
452
      onChangeText={setSearchText}
453
      onSearchButtonPress={handleSearch}
454
      textColor="#000000"
455
      tintColor="#007AFF"
456
    />
457
  );
458
}
459
```
460

461
## Types
462

463
### Search Bar Placement
464

465
```typescript { .api }
466
type SearchBarPlacement = 
467
  | 'automatic'         // System determines placement
468
  | 'inline'            // Inline with navigation bar
469
  | 'stacked'           // Below navigation bar
470
  | 'integrated'        // Integrated into title area (iOS 16.0+)
471
  | 'integratedButton'  // Integrated as button (iOS 16.0+)
472
  | 'integratedCentered'; // Integrated and centered (iOS 16.0+)
473
```
474

475
### Back Button Display Mode
476

477
```typescript { .api }
478
type BackButtonDisplayMode = 
479
  | 'default'  // Show back title if available
480
  | 'generic'  // Show generic back button
481
  | 'minimal'; // Show minimal back button
482
```
483

484
### Blur Effect Types
485

486
```typescript { .api }
487
type BlurEffectTypes = 
488
  | 'none'
489
  | 'extraLight'
490
  | 'light'
491
  | 'dark'
492
  | 'regular'
493
  | 'prominent'
494
  | 'systemUltraThinMaterial'
495
  | 'systemThinMaterial'
496
  | 'systemMaterial'
497
  | 'systemThickMaterial'
498
  | 'systemChromeMaterial'
499
  | 'systemUltraThinMaterialLight'
500
  | 'systemThinMaterialLight'
501
  | 'systemMaterialLight'
502
  | 'systemThickMaterialLight'
503
  | 'systemChromeMaterialLight'
504
  | 'systemUltraThinMaterialDark'
505
  | 'systemThinMaterialDark'
506
  | 'systemMaterialDark'
507
  | 'systemThickMaterialDark'
508
  | 'systemChromeMaterialDark';
509
```
510

511
## Platform Considerations
512

513
### iOS Specific Features
514
- Large title support with custom fonts and colors
515
- Blur effects and translucency
516
- Search bar integration with UISearchController
517
- Back button menu customization
518
- iOS 16+ integrated search placement
519

520
### Android Specific Features
521
- Material Design toolbar styling
522
- Navigation drawer integration
523
- Overflow menu support
524
- Elevation and shadow effects
525

526
### Cross-platform Best Practices
527
- Use platform-appropriate colors and fonts
528
- Respect system theme (light/dark mode)
529
- Maintain native navigation patterns
530
- Test header layouts across screen sizes
531
- Handle RTL languages properly
532

533
### Performance Tips
534
- Minimize custom header components for better performance
535
- Use built-in styling props when possible
536
- Optimize custom images and icons
537
- Avoid complex layouts in header views
538
- Use native search bar for search functionality