You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit bbf8faa
Browse filesBrowse the repository at this point in the historyBrowse files
Read the [Code of Conduct](https://github.com/react-navigation/react-navigation/blob/main/CODE_OF_CONDUCT.md) and [AI Usage Policy](https://github.com/react-navigation/react-navigation/blob/main/AI_POLICY.md) before contributing.
12
+
31
13
### Reporting Bugs
32
14
33
15
You can't write code without writing the occasional bug. Especially as React Navigation is moving quickly, bugs happen. When you think you've found one here's what to do:
Copy file name to clipboardExpand all lines: versioned_docs/version-7.x/drawer-navigator.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -616,7 +616,7 @@ Minimum swipe distance threshold that should activate opening the drawer.
616
616
617
617
#### `keyboardDismissMode`
618
618
619
-
Whether the keyboard should be dismissed when the swipe gesture begins. Defaults to `'on-drag'`. Set to `'none'` to disable keyboard handling.
619
+
Whether the keyboard should be dismissed when the drawer starts opening or closing. Defaults to `'on-drag'`. Set to `'none'` to disable keyboard handling.
Copy file name to clipboardExpand all lines: versioned_docs/version-7.x/elements.md
+3Lines changed: 3 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -358,6 +358,9 @@ It can contain the following properties:
358
358
-`autoCapitalize`: The auto-capitalization behavior. Possible values: `none`, `words`, `sentences`, `characters`.
359
359
-`autoFocus`: Automatically focus search input on mount.
360
360
-`cancelButtonText`: Text to be used instead of default `Cancel` button text (iOS only).
361
+
-`cancelButtonAccessibilityLabel`: Accessibility label for the button that closes the search bar. Defaults to `cancelButtonText` on iOS and `Close` on other platforms.
362
+
-`clearButtonAccessibilityLabel`: Accessibility label for the button that clears the search input. Defaults to `Clear text`.
363
+
-`openButtonAccessibilityLabel`: Accessibility label for the header button that opens the search bar. Defaults to `Search`.
361
364
-`inputType`: Type of the input. Possible values: `text`, `phone`, `number`, `email`.
362
365
-`onBlur`: Callback that gets called when search input has lost focus.
363
366
-`onChangeText`: Callback that gets called when the text changes.
The navigator requires React Native 0.79 or above is required. If you're using [Expo](https://expo.dev/), it requires SDK 53 or above.
54
54
55
-
It also needs `react-native-screens` 4.25.0 or above. If you're using Expo, make sure to use [development builds](https://docs.expo.dev/develop/development-builds/introduction/) instead of Expo Go to use the latest version of `react-native-screens`.
55
+
It also needs `react-native-screens` 4.30.0 or above. If you're using Expo, make sure to use [development builds](https://docs.expo.dev/develop/development-builds/introduction/) instead of Expo Go to use the latest version of `react-native-screens`.
56
56
57
57
## Usage
58
58
@@ -126,14 +126,50 @@ Uses iOS built-in tab bar items with standard iOS styling and localized titles.
126
126
-`search`
127
127
-`topRated`
128
128
129
-
The [`tabBarIcon`](#tabbaricon) and [`tabBarLabel`](#tabbarlabel) options will override the icon and label from the system item. If you want to keep the system behavior on iOS, but need to provide icon and label for other platforms, use `Platform.OS` or `Platform.select` to conditionally set `undefined` for `tabBarIcon` and `tabBarLabel` on iOS.
129
+
The [`tabBarIcon`](#tabbaricon) and [`tabBarLabel`](#tabbarlabel) options override the icon and label from the system item. If you want to keep the system behavior on iOS, but need to provide icon and label for other platforms, use `Platform.OS` or `Platform.select` to conditionally set `undefined` for `tabBarIcon` and `tabBarLabel` on iOS.
130
+
131
+
When set to `search`, the tab may receive prominent visual treatment on iOS 26. See [`tabBarRole`](#tabbarrole) for the behavior on iOS 27 and above.
132
+
133
+
#### `tabBarRole`
134
+
135
+
The role of the tab within the system tab bar. Supported values:
136
+
137
+
-`prominent` - the tab gets prominent visual treatment when supported on iOS 27 and above
138
+
-`search` - the tab is used as the system search tab
139
+
140
+
With the `prominent` role, the tab may receive special styling to make it stand out, such as a separate button next to the tab bar. Only one tab can have the `prominent` role at a time.
On iOS 26.1, a tab with the `search` role gets prominent visual treatment. On iOS 27 and above, it gets prominent styling only if [`tabBarSearchAutoFocus`](#tabbarsearchautofocus) is enabled and no other tab has the `prominent` role. On iOS 27 and above, it also stays visible when the tab bar [minimizes](#tabbarminimizebehavior).
147
+
148
+
The tab uses the system search icon and label by default on iOS. You can override them with [`tabBarSystemItem`](#tabbarsystemitem), [`tabBarIcon`](#tabbaricon), or [`tabBarLabel`](#tabbarlabel).
149
+
150
+
On iOS 26.1 and above, at most one tab can have the `search` role. Adding or removing the `search` role after the tab is rendered is not supported.
151
+
152
+
Also see [Search tab on iOS 26+](#search-tab-on-ios-26).
153
+
154
+
Only supported on iOS.
155
+
156
+
#### `tabBarSearchAutoFocus`
157
+
158
+
Whether the search field is automatically focused when the tab is selected. Cancelling the search selects the previously selected tab.
159
+
160
+
Only applies to tabs with [`tabBarRole`](#tabbarrole) set to `search`, and requires [`headerSearchBarOptions`](native-stack-navigator.md#headersearchbaroptions) to be set in a native stack nested in the tab.
161
+
162
+
Defaults to `false`.
163
+
164
+
Only supported on iOS 26.1 and above.
130
165
131
166
##### Search tab on iOS 26+
132
167
133
-
The `tabBarSystemItem` option has special styling and behavior when set to `search` on iOS 26+.
168
+
The [`tabBarRole`](#tabbarrole) option has special styling and behavior when set to `search` on iOS 26.1 and above.
134
169
135
170
Additionally, when the `search` tab is selected, the tab bar transforms into a search field if:
136
171
172
+
-[`tabBarSearchAutoFocus`](#tabbarsearchautofocus) is enabled
137
173
- The screen has a nested [native stack navigator](native-stack-navigator.md)
138
174
- The focused screen in the nested native stack has [`headerSearchBarOptions`](native-stack-navigator.md#headersearchbaroptions)
@@ -275,9 +313,29 @@ Overrides the label provided by [`tabBarSystemItem`](#tabbarsystemitem) on iOS.
275
313
276
314
If not provided, or set to `undefined`:
277
315
278
-
- The system values are used if [`tabBarSystemItem`](#tabbarsystemitem) is set on iOS.
316
+
- The system values are used on iOS if [`tabBarSystemItem`](#tabbarsystemitem) is set or [`tabBarRole`](#tabbarrole) is `search`.
279
317
- Otherwise, it falls back to the [`title`](#title) or route name.
280
318
319
+
#### `tabBarLabelPositionAdjustment`
320
+
321
+
Offset for the tab label relative to its default position. The offset can be specified separately for each item layout:
322
+
323
+
-`stacked` - icon above the label, such as on iPhone in portrait
324
+
-`inline` - icon beside the label in regular width, such as on iPad
325
+
-`compactInline` - icon beside the label in compact width, such as on iPhone in landscape
326
+
327
+
Each layout accepts `horizontal` and `vertical` offsets. Positive `horizontal` moves the label right, and positive `vertical` moves it down.
328
+
329
+
```js
330
+
tabBarLabelPositionAdjustment: {
331
+
stacked: { horizontal:0, vertical:2 },
332
+
inline: { horizontal:2, vertical:0 },
333
+
compactInline: { horizontal:2, vertical:0 },
334
+
},
335
+
```
336
+
337
+
Only supported on iOS.
338
+
281
339
#### `tabBarLabelVisibilityMode`
282
340
283
341
The label visibility mode for the tab bar items. Supported values:
@@ -346,7 +404,7 @@ The icon can be of following types:
346
404
}
347
405
```
348
406
349
-
The image is tinted by default. Set `tinted` to `false` if the image has its own colors that you want to preserve on iOS. On Android, the image is always tinted and the `tinted` property is ignored.
407
+
The image is tinted by default. Set `tinted` to `false` if the image has its own colors that you want to preserve.
350
408
351
409
-[SF Symbols](https://developer.apple.com/sf-symbols/) name - Supported on iOS
352
410
@@ -357,6 +415,12 @@ The icon can be of following types:
357
415
}
358
416
```
359
417
418
+
The `renderingMode` property can be used to specify how to color the symbol:
419
+
-`monochrome`: Single color, using the tint color.
420
+
-`multicolor`: Uses the symbol's built-in multicolor scheme.
421
+
422
+
System symbols use a single color by default.
423
+
360
424
To render different icons for active and inactive states, you can use a function:
Copy file name to clipboardExpand all lines: versioned_docs/version-7.x/native-stack-navigator.md
+21-1Lines changed: 21 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -424,6 +424,8 @@ Supported values:
424
424
-`landscape_left`: landscape-left orientation is permitted.
425
425
-`landscape_right`: landscape-right orientation is permitted.
426
426
427
+
If not set, the screen inherits the orientation of its parent screen. If no parent screen sets `orientation`, the app's `Info.plist` determines the supported orientations on iOS, and the system decides the best orientation on Android.
428
+
427
429
Only supported on Android and iOS.
428
430
429
431
#### `autoHideHomeIndicator`
@@ -447,7 +449,7 @@ Only supported on iOS.
447
449
448
450
#### `animationDuration`
449
451
450
-
Changes the duration (in milliseconds) of `slide_from_bottom`, `fade_from_bottom`, `fade` and `simple_push` transitions on iOS. Defaults to `350`.
452
+
Changes the duration (in milliseconds) of `slide_from_bottom`, `fade_from_bottom`, `fade` and `simple_push` transitions on iOS. Defaults to `500`.
451
453
452
454
For screens with `default` and `flip` transitions, and, as of now, for screens with `presentation` set to `modal`, `formSheet`, `pageSheet` (regardless of transition), the duration isn't customizable.
453
455
@@ -926,6 +928,14 @@ headerBackVisible: true,
926
928
headerBackTitle:'Back',
927
929
```
928
930
931
+
#### `headerLeftBackgroundVisible`
932
+
933
+
Whether the liquid glass background is visible for the item.
934
+
935
+
Only supported on iOS 26.0 and later. Older versions of iOS and other platforms never show the background.
Whether the liquid glass background is visible for the item.
986
+
987
+
Only supported on iOS 26.0 and later. Older versions of iOS and other platforms never show the background.
988
+
989
+
Defaults to `true`.
990
+
973
991
#### `unstable_headerRightItems`
974
992
975
993
:::warning
@@ -1794,6 +1812,7 @@ Common properties:
1794
1812
- `hidesSharedBackground` (iOS 26+): Whether the background this item may share with other items in the bar should be hidden. Setting this to `true` hides the liquid glass background.
1795
1813
- `sharesBackground` (iOS 26+): Whether this item can share a background with other items. Defaults to `true`.
1796
1814
- `identifier` (iOS 26+) - An identifier used to match items across transitions.
1815
+
- `visibilityPriority` (iOS 27+): Priority used when items in `unstable_headerRightItems` don't fit in the header. Items with lower priority are moved to the overflow menu first. Supported values are `low`, `default`, and `high`. Defaults to `default`.
1797
1816
- `badge` (iOS 26+): An optional badge to display alongside the item. Supported properties:
1798
1817
- `value`: The value to display in the badge. It can be a string or a number.
1799
1818
- `style`: Style object for the badge. Supported properties:
@@ -1858,6 +1877,7 @@ Supported properties when `type` is `menu`:
1858
1877
- `submenu`: An object with the following properties:
1859
1878
- `type`: Must be `submenu`.
1860
1879
- `label`: Label of the submenu item.
1880
+
- `description`: The secondary text displayed alongside the label of the submenu item.
1861
1881
- `icon`: Optional icon to show alongside the label. It accepts the same formats as `icon` above.
1862
1882
1863
1883
- `inline`: Whether the menu is displayed inline with the parent menu. By default, submenus are displayed after expanding the parent menu item. Inline menus are displayed as part of the parent menu as a section. Defaults to `false`.
The screen is lazily evaluated upon render if defined using a getter:
302
+
303
+
```js
304
+
constStack=createNativeStackNavigator({
305
+
screens: {
306
+
Profile:createNativeStackScreen({
307
+
// highlight-start
308
+
getscreen() {
309
+
returnrequire('./ProfileScreen').default;
310
+
},
311
+
// highlight-end
312
+
}),
313
+
},
314
+
});
315
+
```
316
+
317
+
Unlike the regular `screen` property, the getter can only specify screen components and not nested navigator objects.
318
+
319
+
You can use this approach if you want the `ProfileScreen` module to be lazily evaluated with [inline requires](https://reactnative.dev/docs/optimizing-javascript-loading#advanced-call-require-inline).
0 commit comments