0
# Header Components
1

2
Complete header system providing customizable navigation bars, back buttons, titles, and action buttons with platform-specific styling and behavior optimizations for iOS, Android, and Web.
3

4
## Capabilities
5

6
### Header
7

8
Main header component that provides the complete navigation header with support for titles, back buttons, custom left/right actions, search bars, and background customization.
9

10
```typescript { .api }
11
/**
12
 * Main header component for navigation screens
13
 * @param props - Header configuration options
14
 * @returns React element representing the complete header
15
 */
16
function Header(props: {
17
  /** Header title text (required) */
18
  title: string;
19
  /** Back button configuration */
20
  back?: { title: string | undefined; href: string | undefined };
21
  /** Whether header is in modal presentation */
22
  modal?: boolean;
23
  /** Screen layout dimensions */
24
  layout?: Layout;
25
} & HeaderOptions): React.ReactElement;
26
```
27

28
**Usage Examples:**
29

30
```typescript
31
import { Header } from "@react-navigation/elements";
32

33
// Basic header
34
<Header title="Settings" />
35

36
// Header with back button
37
<Header 
38
  title="Profile" 
39
  back={{ title: "Settings" }}
40
/>
41

42
// Customized header
43
<Header
44
  title="Messages"
45
  headerTintColor="#007AFF"
46
  headerStyle={{ backgroundColor: "#f8f9fa" }}
47
  headerRight={({ tintColor }) => (
48
    <HeaderButton onPress={handleAddMessage}>
49
      <Icon name="plus" color={tintColor} />
50
    </HeaderButton>
51
  )}
52
/>
53

54
// Transparent header
55
<Header
56
  title="Photo"
57
  headerTransparent={true}
58
  headerBackground={() => (
59
    <HeaderBackground style={{ backgroundColor: 'rgba(255,255,255,0.9)' }} />
60
  )}
61
/>
62
```
63

64
### HeaderButton
65

66
Generic header button component with platform-specific press effects, accessibility support, and customizable styling.
67

68
```typescript { .api }
69
/**
70
 * Generic header button component with platform-specific press effects
71
 * @param props - Button configuration and content
72
 * @returns React element representing a header button
73
 */
74
const HeaderButton: React.ForwardRefExoticComponent<{
75
  /** Callback when button is pressed */
76
  onPress?: () => void;
77
  /** Web anchor href for link behavior */
78
  href?: string;
79
  /** Whether button is disabled */
80
  disabled?: boolean;
81
  /** Screen reader accessibility label */
82
  accessibilityLabel?: string;
83
  /** Test identifier for automated testing */
84
  testID?: string;
85
  /** Icon and text tint color */
86
  tintColor?: string;
87
  /** Android material ripple color (Android >= 5.0) */
88
  pressColor?: string;
89
  /** Press opacity fallback when ripple not supported */
90
  pressOpacity?: number;
91
  /** Custom button styling */
92
  style?: StyleProp<ViewStyle>;
93
  /** Button content (usually icon or text) */
94
  children: React.ReactNode;
95
}>;
96
```
97

98
**Usage Examples:**
99

100
```typescript
101
import { HeaderButton } from "@react-navigation/elements";
102

103
// Icon button
104
<HeaderButton 
105
  onPress={() => setShowSearch(true)}
106
  accessibilityLabel="Search"
107
>
108
  <Icon name="search" />
109
</HeaderButton>
110

111
// Text button
112
<HeaderButton 
113
  onPress={handleSave}
114
  tintColor="#007AFF"
115
>
116
  <Text>Save</Text>
117
</HeaderButton>
118

119
// Disabled button
120
<HeaderButton 
121
  onPress={handleDelete}
122
  disabled={!canDelete}
123
  tintColor="#FF3B30"
124
>
125
  <Icon name="trash" />
126
</HeaderButton>
127
```
128

129
### HeaderBackButton
130

131
Specialized back button with platform-specific behavior, adaptive label display, and support for custom back icons.
132

133
```typescript { .api }
134
/**
135
 * Navigation back button with platform-specific styling and behavior
136
 * @param props - Back button configuration
137
 * @returns React element representing a back button
138
 */
139
function HeaderBackButton(props: {
140
  /** Callback when button is pressed */
141
  onPress?: () => void;
142
  /** Web anchor href for link behavior */
143
  href?: string;
144
  /** Whether button is disabled */
145
  disabled?: boolean;
146
  /** Screen reader accessibility label */
147
  accessibilityLabel?: string;
148
  /** Test identifier for automated testing */
149
  testID?: string;
150
  /** Icon and text tint color */
151
  tintColor?: string;
152
  /** Android material ripple color */
153
  pressColor?: string;
154
  /** Press opacity fallback */
155
  pressOpacity?: number;
156
  /** Custom button styling */
157
  style?: StyleProp<ViewStyle>;
158
  /** Custom back icon renderer */
159
  backImage?: (props: { tintColor: string }) => React.ReactNode;
160
  /** Button label text (usually previous screen title) */
161
  label?: string;
162
  /** Fallback label when space is limited */
163
  truncatedLabel?: string;
164
  /** How to display icon and title */
165
  displayMode?: HeaderBackButtonDisplayMode;
166
  /** Label text styling */
167
  labelStyle?: Animated.WithAnimatedValue<StyleProp<TextStyle>>;
168
  /** Whether label font should scale for accessibility */
169
  allowFontScaling?: boolean;
170
  /** Label layout change callback */
171
  onLabelLayout?: (e: LayoutChangeEvent) => void;
172
  /** Screen layout dimensions */
173
  screenLayout?: Layout;
174
  /** Title layout dimensions */
175
  titleLayout?: Layout;
176
}): React.ReactElement;
177
```
178

179
**Usage Examples:**
180

181
```typescript
182
import { HeaderBackButton } from "@react-navigation/elements";
183

184
// Standard back button
185
<HeaderBackButton 
186
  onPress={() => navigation.goBack()}
187
  label="Settings"
188
/>
189

190
// Minimal back button (icon only)
191
<HeaderBackButton 
192
  onPress={() => navigation.goBack()}
193
  displayMode="minimal"
194
/>
195

196
// Custom back icon
197
<HeaderBackButton 
198
  onPress={() => navigation.goBack()}
199
  backImage={({ tintColor }) => (
200
    <Icon name="arrow-left" color={tintColor} size={20} />
201
  )}
202
/>
203

204
// Custom styling
205
<HeaderBackButton 
206
  onPress={() => navigation.goBack()}
207
  label="Back"
208
  tintColor="#007AFF"
209
  labelStyle={{ fontSize: 16, fontWeight: 'bold' }}
210
/>
211
```
212

213
### HeaderTitle
214

215
Header title component with platform-specific typography and automatic color theming.
216

217
```typescript { .api }
218
/**
219
 * Header title component with platform-specific typography
220
 * @param props - Title configuration and styling
221
 * @returns React element representing the header title
222
 */
223
function HeaderTitle(props: {
224
  /** Title text content */
225
  children?: string;
226
  /** Whether title font should scale for accessibility */
227
  allowFontScaling?: boolean;
228
  /** Title text color */
229
  tintColor?: string;
230
  /** Title layout change callback */
231
  onLayout?: (e: LayoutChangeEvent) => void;
232
  /** Custom title styling */
233
  style?: Animated.WithAnimatedValue<StyleProp<TextStyle>>;
234
} & Omit<TextProps, 'style'>): React.ReactElement;
235
```
236

237
**Usage Examples:**
238

239
```typescript
240
import { HeaderTitle } from "@react-navigation/elements";
241

242
// Basic title
243
<HeaderTitle>My Screen</HeaderTitle>
244

245
// Styled title
246
<HeaderTitle 
247
  tintColor="#333"
248
  style={{ fontSize: 20, fontWeight: 'bold' }}
249
>
250
  Custom Title
251
</HeaderTitle>
252

253
// Title with layout tracking
254
<HeaderTitle 
255
  onLayout={(e) => setTitleWidth(e.nativeEvent.layout.width)}
256
>
257
  Dynamic Title
258
</HeaderTitle>
259
```
260

261
### HeaderBackground
262

263
Customizable header background container for gradients, images, or blur effects.
264

265
```typescript { .api }
266
/**
267
 * Header background container component
268
 * @param props - Background styling configuration
269
 * @returns React element representing the header background
270
 */
271
function HeaderBackground(props: {
272
  /** Custom background styling */
273
  style?: Animated.WithAnimatedValue<StyleProp<ViewStyle>>;
274
  /** Background content */
275
  children?: React.ReactNode;
276
}): React.ReactElement;
277
```
278

279
**Usage Examples:**
280

281
```typescript
282
import { HeaderBackground } from "@react-navigation/elements";
283

284
// Gradient background
285
<HeaderBackground 
286
  style={{
287
    backgroundColor: 'transparent',
288
    background: 'linear-gradient(45deg, #ff6b6b, #4ecdc4)'
289
  }}
290
/>
291

292
// Image background
293
<HeaderBackground>
294
  <Image 
295
    source={{ uri: 'https://example.com/header-bg.jpg' }}
296
    style={{ width: '100%', height: '100%' }}
297
    resizeMode="cover"
298
  />
299
</HeaderBackground>
300

301
// Blur background
302
<HeaderBackground 
303
  style={{ backgroundColor: 'rgba(255,255,255,0.8)' }}
304
>
305
  <BlurView intensity={80} style={StyleSheet.absoluteFill} />
306
</HeaderBackground>
307
```
308

309
## Platform-Specific Behavior
310

311
### iOS
312
- **Large Titles**: Support for iOS 11+ large title headers
313
- **Back Button**: Automatic label display with previous screen title
314
- **Typography**: Uses iOS system font with appropriate weights
315
- **Animation**: Smooth masked view transitions for back button labels
316
- **Safe Area**: Automatic handling of status bar and notch areas
317

318
### Android
319
- **Material Design**: Follows Material Design 3 guidelines
320
- **Ripple Effects**: Native material ripple on header buttons
321
- **Typography**: Uses Roboto font family with Material Design weights
322
- **Elevation**: Proper shadow elevation for header containers
323
- **Status Bar**: Automatic status bar color coordination
324

325
### Web
326
- **Accessibility**: Proper ARIA labels and semantic HTML
327
- **Hover Effects**: CSS hover states for interactive elements
328
- **Focus Management**: Keyboard navigation support
329
- **Responsive**: Adapts to different screen sizes and orientations