Skip to content

Commit bbf8faa

Browse files
committed
Update docs with new options
1 parent b995543 commit bbf8faa

19 files changed

Lines changed: 374 additions & 76 deletions
Binary file not shown.

‎versioned_docs/version-7.x/bottom-tab-navigator.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -318,6 +318,10 @@ tabBarLabelStyle: {
318318
319319
Function that given `{ focused: boolean, color: string, size: number }` returns a React.Node, to display in the tab bar.
320320
321+
#### `tabBarIconSize`
322+
323+
Size of the tab's icon.
324+
321325
#### `tabBarIconStyle`
322326
323327
Style object for the tab icon.

‎versioned_docs/version-7.x/contributing.md‎

Lines changed: 2 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -6,28 +6,10 @@ sidebar_label: Contributing
66

77
Want to help improve React Navigation? Your help would be greatly appreciated!
88

9-
Here are some of the ways to contribute to the project:
10-
11-
- [Contributing](#contributing)
12-
- [Reporting Bugs](#reporting-bugs)
13-
- [Improving the Documentation](#improving-the-documentation)
14-
- [Responding to Issues](#responding-to-issues)
15-
- [Bug Fixes](#bug-fixes)
16-
- [Suggesting a Feature](#suggesting-a-feature)
17-
- [Big Pull Requests](#big-pull-requests)
18-
19-
And here are a few helpful resources to aid in getting started:
20-
21-
- [Information](#information)
22-
- [Issue Template](#issue-template)
23-
- [Pull Request Template](#pull-request-template)
24-
- [Forking the Repository](#forking-the-repository)
25-
- [Code Review Guidelines](#code-review-guidelines)
26-
- [Run the Example App](#run-the-example-app)
27-
- [Run Tests](#run-tests)
28-
299
## Contributing
3010

11+
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+
3113
### Reporting Bugs
3214

3315
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:

‎versioned_docs/version-7.x/drawer-layout.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -138,10 +138,10 @@ Whether to hide the status bar when the drawer is open. Defaults to `false`.
138138

139139
##### `keyboardDismissMode`
140140

141-
Whether to dismiss the keyboard when the drawer is open. Supported values are:
141+
Whether to dismiss the keyboard when the drawer starts opening or closing. Supported values are:
142142

143-
- `none`: The keyboard will not be dismissed when the drawer is open.
144-
- `on-drag`: The keyboard will be dismissed when the drawer is opened by a swipe gesture.
143+
- `none`: The keyboard will not be dismissed by the drawer.
144+
- `on-drag`: The keyboard will be dismissed when the drawer starts opening or closing.
145145

146146
Defaults to `on-drag`.
147147

‎versioned_docs/version-7.x/drawer-navigator.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -616,7 +616,7 @@ Minimum swipe distance threshold that should activate opening the drawer.
616616

617617
#### `keyboardDismissMode`
618618

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.
620620

621621
#### `freezeOnBlur`
622622

‎versioned_docs/version-7.x/elements.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -358,6 +358,9 @@ It can contain the following properties:
358358
- `autoCapitalize`: The auto-capitalization behavior. Possible values: `none`, `words`, `sentences`, `characters`.
359359
- `autoFocus`: Automatically focus search input on mount.
360360
- `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`.
361364
- `inputType`: Type of the input. Possible values: `text`, `phone`, `number`, `email`.
362365
- `onBlur`: Callback that gets called when search input has lost focus.
363366
- `onChangeText`: Callback that gets called when the text changes.

‎versioned_docs/version-7.x/native-bottom-tab-navigator.md‎

Lines changed: 116 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ npm install @react-navigation/bottom-tabs
5252

5353
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.
5454

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`.
5656

5757
## Usage
5858

@@ -126,14 +126,50 @@ Uses iOS built-in tab bar items with standard iOS styling and localized titles.
126126
- `search`
127127
- `topRated`
128128

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.
141+
142+
<video playsInline autoPlay muted loop>
143+
<source src="/assets/navigators/bottom-tabs/highlights/prominent-tab.mp4" />
144+
</video>
145+
146+
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.
130165

131166
##### Search tab on iOS 26+
132167

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.
134169

135170
Additionally, when the `search` tab is selected, the tab bar transforms into a search field if:
136171

172+
- [`tabBarSearchAutoFocus`](#tabbarsearchautofocus) is enabled
137173
- The screen has a nested [native stack navigator](native-stack-navigator.md)
138174
- The focused screen in the nested native stack has [`headerSearchBarOptions`](native-stack-navigator.md#headersearchbaroptions)
139175

@@ -148,7 +184,7 @@ import {
148184
createStaticNavigation,
149185
useNavigation,
150186
} from '@react-navigation/native';
151-
import { createBottomTabNavigator } from '@react-navigation/bottom-tabs';
187+
import { createNativeBottomTabNavigator } from '@react-navigation/bottom-tabs/unstable';
152188
import { createNativeStackNavigator } from '@react-navigation/native-stack';
153189

154190
const DATA = [
@@ -227,7 +263,7 @@ const SearchStack = createNativeStackNavigator({
227263
},
228264
});
229265

230-
const HomeTabs = createBottomTabNavigator({
266+
const HomeTabs = createNativeBottomTabNavigator({
231267
screens: {
232268
Home: {
233269
screen: HomeScreen,
@@ -248,8 +284,10 @@ const HomeTabs = createBottomTabNavigator({
248284
// highlight-next-line
249285
screen: SearchStack,
250286
options: {
251-
// highlight-next-line
252-
tabBarSystemItem: 'search',
287+
// highlight-start
288+
tabBarRole: 'search',
289+
tabBarSearchAutoFocus: true,
290+
// highlight-end
253291
},
254292
},
255293
},
@@ -275,9 +313,29 @@ Overrides the label provided by [`tabBarSystemItem`](#tabbarsystemitem) on iOS.
275313

276314
If not provided, or set to `undefined`:
277315

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`.
279317
- Otherwise, it falls back to the [`title`](#title) or route name.
280318

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+
281339
#### `tabBarLabelVisibilityMode`
282340

283341
The label visibility mode for the tab bar items. Supported values:
@@ -346,7 +404,7 @@ The icon can be of following types:
346404
}
347405
```
348406

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.
350408

351409
- [SF Symbols](https://developer.apple.com/sf-symbols/) name - Supported on iOS
352410

@@ -357,6 +415,12 @@ The icon can be of following types:
357415
}
358416
```
359417

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+
360424
To render different icons for active and inactive states, you can use a function:
361425

362426
```js
@@ -385,6 +449,14 @@ tabBarIcon: Platform.select({
385449
});
386450
```
387451

452+
#### `tabBarIconSize`
453+
454+
Size of the tab's icon.
455+
456+
The largest size is used for the icon area in all tabs. Icons smaller than the largest size are centered in this area.
457+
458+
Only supported on Android.
459+
388460
#### `tabBarBadge`
389461

390462
Text to show in a badge on the tab icon. Accepts a `string` or a `number`.
@@ -418,8 +490,6 @@ Color for the icon and label in the active tab.
418490

419491
Color for the icon and label in the inactive tabs.
420492

421-
Only supported on Android.
422-
423493
#### `tabBarActiveIndicatorColor`
424494

425495
Background color of the active indicator.
@@ -432,12 +502,30 @@ Whether the active indicator should be used. Defaults to `true`.
432502

433503
Only supported on Android.
434504

505+
#### `tabBarActiveIndicatorWidth`
506+
507+
Width of the tab's active indicator.
508+
509+
Only supported on Android.
510+
511+
#### `tabBarActiveIndicatorHeight`
512+
513+
Height of the tab's active indicator.
514+
515+
Only supported on Android.
516+
435517
#### `tabBarRippleColor`
436518

437519
Color of the ripple effect when pressing a tab.
438520

439521
Only supported on Android.
440522

523+
#### `tabBarVisibilityAnimationEnabled`
524+
525+
Whether showing and hiding the tab bar is animated. Defaults to `true`.
526+
527+
Only supported on iOS 18 and above.
528+
441529
#### `tabBarStyle`
442530

443531
Style object for the tab bar. Supported properties:
@@ -490,12 +578,28 @@ The display mode for the tab bar. Supported values:
490578

491579
Only supported on iOS 18 and above. Not supported on tvOS.
492580

581+
#### `tabBarSidebarPreferredPlacement`
582+
583+
Whether the sidebar or the tab bar is preferred when only one of them can be displayed. Supported values:
584+
585+
- `auto` - uses the system default (tab bar)
586+
- `sidebar` - the sidebar is displayed when it's available
587+
- `tabBar` - the tab bar is displayed
588+
589+
Requires [`tabBarControllerMode`](#tabbarcontrollermode) to be set to `tabSidebar`.
590+
591+
The sidebar is only available when the horizontal size class is regular, e.g. on iPad, or on larger iPhones in landscape.
592+
593+
Defaults to `auto`.
594+
595+
Only supported on iOS 27 and above. Not supported on tvOS.
596+
493597
#### `tabBarMinimizeBehavior`
494598

495599
The minimize behavior for the tab bar. Supported values:
496600

497601
- `auto` - resolves to the system default minimize behavior
498-
- `never` - the tab bar does not minimize
602+
- `none` - the tab bar does not minimize
499603
- `onScrollDown` - the tab bar minimizes when scrolling down and
500604
expands when scrolling back up
501605
- `onScrollUp` - the tab bar minimizes when scrolling up and expands

‎versioned_docs/version-7.x/native-stack-navigator.md‎

Lines changed: 21 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -424,6 +424,8 @@ Supported values:
424424
- `landscape_left`: landscape-left orientation is permitted.
425425
- `landscape_right`: landscape-right orientation is permitted.
426426

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+
427429
Only supported on Android and iOS.
428430

429431
#### `autoHideHomeIndicator`
@@ -447,7 +449,7 @@ Only supported on iOS.
447449

448450
#### `animationDuration`
449451

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`.
451453

452454
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.
453455

@@ -926,6 +928,14 @@ headerBackVisible: true,
926928
headerBackTitle: 'Back',
927929
```
928930

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.
936+
937+
Defaults to `true`.
938+
929939
#### `unstable_headerLeftItems`
930940

931941
:::warning
@@ -970,6 +980,14 @@ Example:
970980
headerRight: () => <MaterialCommunityIcons name="map" color="blue" size={36} />;
971981
```
972982

983+
#### `headerRightBackgroundVisible`
984+
985+
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+
973991
#### `unstable_headerRightItems`
974992

975993
:::warning
@@ -1794,6 +1812,7 @@ Common properties:
17941812
- `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.
17951813
- `sharesBackground` (iOS 26+): Whether this item can share a background with other items. Defaults to `true`.
17961814
- `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`.
17971816
- `badge` (iOS 26+): An optional badge to display alongside the item. Supported properties:
17981817
- `value`: The value to display in the badge. It can be a string or a number.
17991818
- `style`: Style object for the badge. Supported properties:
@@ -1858,6 +1877,7 @@ Supported properties when `type` is `menu`:
18581877
- `submenu`: An object with the following properties:
18591878
- `type`: Must be `submenu`.
18601879
- `label`: Label of the submenu item.
1880+
- `description`: The secondary text displayed alongside the label of the submenu item.
18611881
- `icon`: Optional icon to show alongside the label. It accepts the same formats as `icon` above.
18621882
18631883
- `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`.

‎versioned_docs/version-7.x/screen.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -298,6 +298,26 @@ const Stack = createNativeStackNavigator({
298298
});
299299
```
300300

301+
The screen is lazily evaluated upon render if defined using a getter:
302+
303+
```js
304+
const Stack = createNativeStackNavigator({
305+
screens: {
306+
Profile: createNativeStackScreen({
307+
// highlight-start
308+
get screen() {
309+
return require('./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).
320+
301321
</TabItem>
302322
<TabItem value="dynamic">
303323

0 commit comments

Comments
 (0)