Skip to content

Commit 88427b9

Browse files
satya164satya164
committed
Update docs for React Navigation 8
1 parent a961d8c commit 88427b9

27 files changed

+1757
-1705
lines changed

‎blog/2025-12-03-react-navigation-8.0-alpha.md‎

Lines changed: 202 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,202 @@
1+
---
2+
title: React Navigation 8.0 Alpha
3+
authors: satya
4+
tags: [announcement]
5+
---
6+
7+
We're excited to announce the first alpha release of React Navigation 8.0.
8+
9+
This release focuses on improved TypeScript types for static configuration, native bottom tabs as the default, and various other improvements and new features. And there are many more improvements planned for the final release.
10+
11+
<!--truncate-->
12+
13+
You can read the full list of changes in the [upgrade guide](/docs/8.x/upgrading-from-7.x). Here are some highlights:
14+
15+
## Highlights
16+
17+
### Native Bottom Tabs by default
18+
19+
The Bottom Tab Navigator now uses native implementations by default on iOS and Android based on [`react-native-screens`](https://github.com/software-mansion/react-native-screens). This lets us to support the new liquid glass effect on iOS 26 and provide a more native feel by default. Making it default also helps with adoption.
20+
21+
<video playsInline autoPlay muted loop>
22+
<source src="/assets/7.x/native-bottom-tabs-android.mp4" />
23+
</video>
24+
25+
<video playsInline autoPlay muted loop>
26+
<source src="/assets/7.x/native-bottom-tabs-ios.mp4" />
27+
</video>
28+
29+
We also include a custom JS based implementation in order to support Web and more customization options. You can switch to the JS implementation by passing the `implementation` prop to the navigator.
30+
31+
See [Bottom Tab Navigator docs](/docs/8.x/bottom-tab-navigator) for more details.
32+
33+
### Ability to get `route`, `navigation`, and state for any parent screen
34+
35+
Hooks such as `useRoute`, `useNavigation`, and `useNavigationState` now accept a screen to get the corresponding `route`, `navigation`, and state respectively for any parent screen The `navigation` object already had a `getParent` method, so this is not a new capability for `useNavigation`, but it was not possible for `useRoute` and `useNavigationState` before.
36+
37+
One of the commonly requested features has been for screens to be able to access the params for parent screens, but this had a few problems:
38+
39+
- Passing down params to child screens may lead to unnecessary re-renders when the parent params change, even when they are not needed by the child screen.
40+
- Since the param types are defined by the screen itself, having additional parent params would not be compatible with the existing type system.
41+
42+
It was necessary to manually setup React Context to pass down parent params, which was cumbersome.
43+
44+
The screen name parameter in `useRoute` solves these problems. Now, you can access the parent route and its params directly by specifying the screen name:
45+
46+
```js
47+
const route = useRoute('Profile');
48+
49+
console.log(route.params); // Params for the 'Profile' screen
50+
```
51+
52+
Similarly, you can get the `navigation` object for any parent screen:
53+
54+
```js
55+
const navigation = useNavigation('Profile');
56+
57+
console.log(navigation); // Navigation object for the 'Profile' screen
58+
```
59+
60+
And you can get the navigation state for any parent screen:
61+
62+
```js
63+
const focusedRoute = useNavigationState(
64+
'Profile',
65+
(state) => state.routes[state.index]
66+
);
67+
68+
console.log(focusedRoute); // Focused route for the navigator which contains the 'Profile' screen
69+
```
70+
71+
See [`useRoute`](/docs/8.x/use-route), [`useNavigation`](/docs/8.x/use-navigation), and [`useNavigationState`](/docs/8.x/use-navigation-state) for more details.
72+
73+
### Better TypeScript types for static configuration
74+
75+
In React Navigation 7, we introduced a static API for configuring navigators. However, some TypeScript types required manual annotations. We've reworked the types to solve many of these issues.
76+
77+
Hooks like `useNavigation`, `useRoute`, and `useNavigationState` now automatically infer types based on the provided screen name:
78+
79+
```js
80+
const navigation = useNavigation('Profile');
81+
82+
// navigation is correctly typed as StackNavigationProp<RootStackParamList, 'Profile'>
83+
```
84+
85+
The `navigation` object will now have proper types based on navigator nesting, and will include navigator specific methods such as `openDrawer` for drawer navigators or `push` for stack navigators without requiring manual type annotations.
86+
87+
Similarly, `useRoute` will return the correct route type with properly typed params:
88+
89+
```js
90+
const route = useRoute('Profile');
91+
92+
// route is correctly typed as RouteProp<RootStackParamList, 'Profile'>
93+
```
94+
95+
And `useNavigationState` will infer the correct state type for the specified screen:
96+
97+
```js
98+
const focusedRoute = useNavigationState(
99+
'Profile',
100+
(state) => state.routes[state.index]
101+
);
102+
103+
// state is correctly typed as StackNavigationState<RootStackParamList>
104+
```
105+
106+
In addition, previously, the type of `route` object can't be inferred in screen callback, listeners callback etc. This made it difficult to use route params in these callbacks.
107+
108+
The new `createXScreen` helper functions addresses this:
109+
110+
```js
111+
const Stack = createStackNavigator({
112+
screens: {
113+
Profile: createStackScreen({
114+
screen: ProfileScreen,
115+
options: ({ route }) => {
116+
const userId = route.params.userId;
117+
118+
return {
119+
title: `${userId}'s profile`
120+
};
121+
},
122+
});
123+
}
124+
});
125+
```
126+
127+
Here, the type of `route.params` is correctly inferred based on the type annotation of `ProfileScreen`. Each navigator exports its own helper function, e.g. `createNativeStackScreen` for Native Stack Navigator, `createBottomTabScreen` for Bottom Tab Navigator, `createDrawerScreen` for Drawer Navigator etc.
128+
129+
See [TypeScript docs](/docs/8.x/typescript) and [Static configuration docs](/docs/8.x/static-configuration) for more details.
130+
131+
### Pushing history entries without pushing new screens
132+
133+
One of the things React Navigation lacked was to add a new history entry without pushing a new screen. But this is not always desirable, as pushing a new screen adds an entirely new instance of the screen component, and shows transition animations.
134+
135+
This is useful for many scenarios:
136+
137+
- A product listing page with filters, where changing filters should create a new history entry so that users can go back to previous filter states.
138+
- A screen with a custom modal component, where the modal is not a separate screen in the navigator, but its state should be reflected in the URL and history.
139+
140+
Especially on the web, users expect that changing certain UI states should create a new history entry, so that they can use the browser back and forward buttons to navigate through these states.
141+
142+
The new `pushParams` API makes this possible. You can now push an entry to the history stack by adding new params without needing to push a new screen.
143+
144+
See [`pushParams` docs](/docs/8.x/navigation-object#pushparams) for more details.
145+
146+
### Replacing params
147+
148+
Previously, the only way to update screen params was via the `setParams` action, it took an object containing the params and merged them with the existing params. But removing params required setting them to `undefined`, which was not very intuitive.
149+
150+
The new `replaceParams` action replaces params entirely instead of merging them. This makes it easier to use a new set of params without needing to worry about removing old params.
151+
152+
See [`replaceParams` docs](/docs/8.x/navigation-object#replaceparams) for more details.
153+
154+
### Support for `PlatformColor`, `DynamicColorIOS` and CSS custom properties in theme colors
155+
156+
React Navigation has its own theming system to change styling for the built-in components. Previously, it only supported string color values. In this release, we've added support for platform-specific dynamic colors such as `PlatformColor` and `DynamicColorIOS` on native, as well as CSS custom properties on the web.
157+
158+
This makes it easier to use system colors as well as share colors across native components and React Navigation components.
159+
160+
```js
161+
const MyTheme = {
162+
...DefaultTheme,
163+
colors: Platform.select({
164+
ios: () => ({
165+
primary: PlatformColor('systemRed'),
166+
background: PlatformColor('systemGroupedBackground'),
167+
// ...
168+
}),
169+
android: () => ({
170+
primary: PlatformColor('@android:color/system_primary_light'),
171+
// ...
172+
}),
173+
default: () => DefaultTheme.colors,
174+
})(),
175+
};
176+
```
177+
178+
This comes with one limitation: with string colors, React Navigation can automatically adjust colors in some scenarios (e.g. adjust the text color based on background color), which is not possible with dynamic colors. So it will fallback to pre-defined colors according to the theme in these cases.
179+
180+
See [Themes docs](/docs/8.x/themes) for more details.
181+
182+
## Try it out
183+
184+
If you'd like to try it out, add `@alpha` to the package you're installing. For example:
185+
186+
```sh npm2yarn
187+
npm install @react-navigation/native@alpha @react-navigation/bottom-tabs@alpha
188+
```
189+
190+
Your feedback is very important to us to ensure a smooth final release. If you encounter any issues or have any feedback or suggestions, please let us know on [GitHub issues](https://github.com/react-navigation/react-navigation/issues) or our [GitHub Discussions forum](https://github.com/react-navigation/react-navigation/discussions).
191+
192+
## Special thanks
193+
194+
React Navigation 8 would not have been possible without our amazing contributors.
195+
196+
Thanks a lot to [Michał Osadnik](https://x.com/mosdnk), [Kacper Kafara](https://x.com/kafara_kacper), [Krzystof Ligarski](https://github.com/kligarski), [Tomasz Boroń](https://github.com/t0maboro), [Konrad Michalik](https://github.com/kmichalikk), [Oskar Kwaśniewski](https://github.com/okwasniewski) and many others for their contributions to this release.
197+
198+
## Sponsor us
199+
200+
If React Navigation helps you to deliver value to your customers, it'd mean a lot if you could sponsor us. Sponsorships will help us to move more quickly towards our goal of building the best cross-platform navigation library and continue to provide timely support for bug reports in our GitHub issues.
201+
202+
👉 [Visit our GitHub Sponsors page](https://github.com/sponsors/react-navigation) 👈

0 commit comments

Comments
 (0)