0
# React Navigation Elements
1

2
React Navigation Elements provides a comprehensive collection of UI components specifically designed for React Navigation applications. It offers reusable components for navigation interfaces including headers, buttons, layout components, and utility functions, all with cross-platform support for iOS, Android, and Web.
3

4
## Package Information
5

6
- **Package Name**: @react-navigation/elements
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @react-navigation/elements`
10

11
## Core Imports
12

13
```typescript
14
import {
15
  Header,
16
  Button,
17
  Screen,
18
  HeaderButton,
19
  HeaderBackButton,
20
  useHeaderHeight,
21
  useFrameSize,
22
  FrameSizeProvider,
23
} from "@react-navigation/elements";
24
```
25

26
For CommonJS:
27

28
```javascript
29
const {
30
  Header,
31
  Button,
32
  Screen,
33
  HeaderButton,
34
  HeaderBackButton,
35
  useHeaderHeight,
36
  useFrameSize,
37
  FrameSizeProvider,
38
} = require("@react-navigation/elements");
39
```
40

41
## Basic Usage
42

43
```typescript
44
import React from "react";
45
import {
46
  Header,
47
  Screen,
48
  HeaderBackButton,
49
  HeaderTitle,
50
  Button,
51
  useHeaderHeight,
52
} from "@react-navigation/elements";
53

54
// Basic header setup
55
function MyScreen({ navigation, route }) {
56
  const headerHeight = useHeaderHeight();
57
  
58
  return (
59
    <Screen
60
      focused={true}
61
      navigation={navigation}
62
      route={route}
63
      header={
64
        <Header
65
          title="My Screen"
66
          back={{ title: "Back" }}
67
          headerLeft={(props) => (
68
            <HeaderBackButton
69
              {...props}
70
              onPress={() => navigation.goBack()}
71
            />
72
          )}
73
        />
74
      }
75
    >
76
      <Button
77
        variant="filled"
78
        onPress={() => console.log("Button pressed")}
79
      >
80
        Press me
81
      </Button>
82
    </Screen>
83
  );
84
}
85
```
86

87
## Architecture
88

89
React Navigation Elements is built around several key architectural patterns:
90

91
- **Header System**: Complete header component with customizable left/right actions, titles, and backgrounds
92
- **Screen Management**: Screen wrapper component that provides navigation context and header integration
93
- **Cross-Platform Components**: Platform-specific optimizations for iOS, Android, and Web
94
- **Context Providers**: React contexts for sharing header state, dimensions, and navigation information
95
- **Theme Integration**: Automatic theme color application across all components
96
- **Performance Optimization**: Components like ResourceSavingView for efficient rendering
97

98
## Capabilities
99

100
### Header Components
101

102
Complete header system with customizable navigation bars, back buttons, titles, and action buttons. Includes platform-specific styling and behavior.
103

104
```typescript { .api }
105
function Header(props: {
106
  title: string;
107
  back?: { title: string | undefined; href: string | undefined };
108
  modal?: boolean;
109
  layout?: Layout;
110
} & HeaderOptions): React.ReactElement;
111

112
function HeaderBackButton(props: HeaderBackButtonProps): React.ReactElement;
113

114
function HeaderButton(props: HeaderButtonProps): React.ReactElement;
115

116
function HeaderTitle(props: HeaderTitleProps): React.ReactElement;
117
```
118

119
[Header Components](./header-components.md)
120

121
### Layout Components
122

123
Core layout components for structuring navigation screens, managing safe areas, and providing themed backgrounds.
124

125
```typescript { .api }
126
function Screen(props: {
127
  focused: boolean;
128
  modal?: boolean;
129
  navigation: NavigationProp<ParamListBase>;
130
  route: RouteProp<ParamListBase>;
131
  header: React.ReactNode;
132
  headerShown?: boolean;
133
  headerStatusBarHeight?: number;
134
  headerTransparent?: boolean;
135
  style?: Animated.WithAnimatedValue<StyleProp<ViewStyle>>;
136
  children: React.ReactNode;
137
}): React.ReactElement;
138

139
function Background(props: {
140
  style?: Animated.WithAnimatedValue<StyleProp<ViewStyle>>;
141
  children: React.ReactNode;
142
}): React.ReactElement;
143

144
function SafeAreaProviderCompat(props: {
145
  children: React.ReactNode;
146
  style?: StyleProp<ViewStyle>;
147
}): React.ReactElement;
148
```
149

150
[Layout Components](./layout-components.md)
151

152
### Interactive Components
153

154
Button and pressable components with navigation integration, platform-specific press effects, and theme support.
155

156
```typescript { .api }
157
// Basic button with onPress handler
158
function Button(props: ButtonBaseProps): React.ReactElement;
159

160
// Navigation button with screen/action routing
161
function Button<ParamList extends ReactNavigation.RootParamList>(
162
  props: ButtonLinkProps<ParamList>
163
): React.ReactElement;
164

165
const PlatformPressable: React.ForwardRefExoticComponent<{
166
  href?: string;
167
  pressColor?: string;
168
  pressOpacity?: number;
169
  hoverEffect?: HoverEffectProps;
170
  style?: Animated.WithAnimatedValue<StyleProp<ViewStyle>>;
171
  onPress?: (e: React.MouseEvent | GestureResponderEvent) => void;
172
  children: React.ReactNode;
173
} & Omit<PressableProps, 'style' | 'onPress'>>;
174
```
175

176
[Interactive Components](./interactive-components.md)
177

178
### Utility Components
179

180
Text, label, icon, and performance optimization components for common navigation UI patterns.
181

182
```typescript { .api }
183
function Text(props: TextProps): React.ReactElement;
184

185
function Label(props: {
186
  tintColor?: string;
187
  children?: string;
188
  style?: StyleProp<TextStyle>;
189
} & Omit<TextProps, 'style'>): React.ReactElement;
190

191
function MissingIcon(props: {
192
  color?: string;
193
  size?: number;
194
  style?: StyleProp<TextStyle>;
195
}): React.ReactElement;
196

197
function ResourceSavingView(props: {
198
  visible: boolean;
199
  children: React.ReactNode;
200
  style?: StyleProp<ViewStyle>;
201
}): React.ReactElement;
202
```
203

204
[Utility Components](./utility-components.md)
205

206
### Hooks and Contexts
207

208
React hooks and context providers for accessing navigation state, dimensions, and header information.
209

210
```typescript { .api }
211
function useHeaderHeight(): number;
212

213
function useFrameSize<T>(
214
  selector: (frame: Frame) => T,
215
  throttle?: boolean
216
): T;
217

218
function FrameSizeProvider(props: {
219
  initialFrame: Frame;
220
  children: React.ReactNode;
221
  style?: StyleProp<ViewStyle>;
222
}): React.ReactElement;
223

224
const HeaderBackContext: React.Context<{ title: string | undefined; href: string | undefined } | undefined>;
225
const HeaderHeightContext: React.Context<number | undefined>;
226
const HeaderShownContext: React.Context<boolean>;
227
```
228

229
[Hooks and Contexts](./hooks-contexts.md)
230

231
### Utility Functions
232

233
Helper functions for calculating dimensions, resolving titles and labels, and other common navigation tasks.
234

235
```typescript { .api }
236
function getDefaultHeaderHeight(
237
  layout: Layout,
238
  modalPresentation: boolean,
239
  topInset: number
240
): number;
241

242
function getDefaultSidebarWidth({ width }: { width: number }): number;
243

244
function getHeaderTitle(
245
  options: { title?: string; headerTitle?: HeaderOptions['headerTitle'] },
246
  fallback: string
247
): string;
248

249
function getLabel(
250
  options: { label?: string; title?: string },
251
  fallback: string
252
): string;
253
```
254

255
[Utility Functions](./utility-functions.md)
256

257
## Types
258

259
Core type definitions used throughout the library:
260

261
```typescript { .api }
262
interface Layout {
263
  width: number;
264
  height: number;
265
}
266

267
type HeaderBackButtonDisplayMode = 'default' | 'generic' | 'minimal';
268

269
interface HeaderOptions {
270
  headerTitle?: string | ((props: HeaderTitleProps) => React.ReactNode);
271
  headerTitleAlign?: 'left' | 'center';
272
  headerTitleStyle?: Animated.WithAnimatedValue<StyleProp<TextStyle>>;
273
  headerTitleContainerStyle?: Animated.WithAnimatedValue<StyleProp<ViewStyle>>;
274
  headerTitleAllowFontScaling?: boolean;
275
  headerSearchBarOptions?: HeaderSearchBarOptions;
276
  headerLeft?: (props: HeaderBackButtonProps & { canGoBack?: boolean }) => React.ReactNode;
277
  headerBackButtonDisplayMode?: HeaderBackButtonDisplayMode;
278
  headerBackTitleStyle?: StyleProp<{ fontFamily?: string; fontSize?: number }>;
279
  headerLeftContainerStyle?: Animated.WithAnimatedValue<StyleProp<ViewStyle>>;
280
  headerRight?: (props: { tintColor?: string; pressColor?: string; pressOpacity?: number; canGoBack: boolean }) => React.ReactNode;
281
  headerRightContainerStyle?: Animated.WithAnimatedValue<StyleProp<ViewStyle>>;
282
  headerPressColor?: string;
283
  headerPressOpacity?: number;
284
  headerTintColor?: string;
285
  headerBackground?: (props: { style: Animated.WithAnimatedValue<StyleProp<ViewStyle>> }) => React.ReactNode;
286
  headerBackgroundContainerStyle?: Animated.WithAnimatedValue<StyleProp<ViewStyle>>;
287
  headerTransparent?: boolean;
288
  headerStyle?: Animated.WithAnimatedValue<StyleProp<ViewStyle>>;
289
  headerShadowVisible?: boolean;
290
  headerStatusBarHeight?: number;
291
}
292

293
interface HeaderTitleProps {
294
  children: string;
295
  allowFontScaling?: boolean;
296
  tintColor?: string;
297
  onLayout?: (e: LayoutChangeEvent) => void;
298
  style?: Animated.WithAnimatedValue<StyleProp<TextStyle>>;
299
}
300

301
interface HeaderButtonProps {
302
  onPress?: () => void;
303
  href?: string;
304
  disabled?: boolean;
305
  accessibilityLabel?: string;
306
  testID?: string;
307
  tintColor?: string;
308
  pressColor?: string;
309
  pressOpacity?: number;
310
  style?: StyleProp<ViewStyle>;
311
  children: React.ReactNode;
312
}
313

314
interface HeaderBackButtonProps extends Omit<HeaderButtonProps, 'children'> {
315
  backImage?: (props: { tintColor: string }) => React.ReactNode;
316
  label?: string;
317
  truncatedLabel?: string;
318
  displayMode?: HeaderBackButtonDisplayMode;
319
  labelStyle?: Animated.WithAnimatedValue<StyleProp<TextStyle>>;
320
  allowFontScaling?: boolean;
321
  onLabelLayout?: (e: LayoutChangeEvent) => void;
322
  screenLayout?: Layout;
323
  titleLayout?: Layout;
324
}
325

326
interface HeaderSearchBarOptions {
327
  ref?: React.Ref<HeaderSearchBarRef>;
328
  autoCapitalize?: 'none' | 'words' | 'sentences' | 'characters';
329
  autoFocus?: boolean;
330
  cancelButtonText?: string;
331
  inputType?: 'text' | 'phone' | 'number' | 'email';
332
  enterKeyHint?: TextInputProps['enterKeyHint'];
333
  onBlur?: TextInputProps['onBlur'];
334
  onChangeText?: TextInputProps['onChange'];
335
  onSubmitEditing?: TextInputProps['onSubmitEditing'];
336
  onOpen?: () => void;
337
  onClose?: () => void;
338
  onFocus?: TextInputProps['onFocus'];
339
  placeholder?: string;
340
}
341

342
interface HeaderSearchBarRef {
343
  focus: () => void;
344
  blur: () => void;
345
  setText: (text: string) => void;
346
  clearText: () => void;
347
  cancelSearch: () => void;
348
}
349

350
interface Layout {
351
  width: number;
352
  height: number;
353
}
354

355
// Frame is an alias for Layout used in frame sizing functions
356
type Frame = Layout;
357

358
type PlatformPressableProps = {
359
  href?: string;
360
  pressColor?: string;
361
  pressOpacity?: number;
362
  hoverEffect?: HoverEffectProps;
363
  style?: Animated.WithAnimatedValue<StyleProp<ViewStyle>>;
364
  onPress?: (e: React.MouseEvent | GestureResponderEvent) => void;
365
  children: React.ReactNode;
366
} & Omit<PressableProps, 'style' | 'onPress'>;
367

368
type ButtonBaseProps = Omit<PlatformPressableProps, 'children'> & {
369
  variant?: 'plain' | 'tinted' | 'filled';
370
  color?: string;
371
  children: string | string[];
372
};
373

374
type ButtonLinkProps<ParamList extends ReactNavigation.RootParamList> = {
375
  screen: keyof ParamList;
376
  params?: ParamList[keyof ParamList];
377
  action?: NavigationAction;
378
  href?: string;
379
} & Omit<ButtonBaseProps, 'onPress'>;
380

381
interface HoverEffectProps {
382
  color?: string;
383
  hoverOpacity?: number;
384
  activeOpacity?: number;
385
}
386
```
387

388
## Constants
389

390
```typescript { .api }
391
const Assets: (string | number)[];
392
```
393

394
The Assets array contains image resources for common navigation icons:
395
- `backIcon` - Navigation back arrow icon
396
- `backIconMask` - Back icon mask for iOS transitions
397
- `searchIcon` - Search magnifying glass icon
398
- `closeIcon` - Close/dismiss X icon  
399
- `clearIcon` - Clear/reset icon