Skip to content

React Navigation 5.0 is stable with a component-based API

updated

React Navigation 5.0 has been marked stable, two years after the library's first stable release. The release follows six months of refactoring that rewrote the core of the library and reshaped its API.

Configuration moves into components

The headline change is how navigators are configured. Earlier versions relied on createXNavigator functions and static navigationOptions. In version 5, configuration happens inside components and is dynamic:

function App() {
  return (
    <Stack.Navigator initialRouteName="home">
      <Stack.Screen name="settings" component={Settings} />
      <Stack.Screen
        name="profile"
        component={Profile}
        options={{ title: 'John Doe' }}
      />
    </Stack.Navigator>
  );
}

Because configuration now happens in components, it has access to props, state and context, and can change at runtime. The maintainers describe this as the most important change in the release, and say it brings navigation configuration in line with common React patterns.

Hooks and setOptions

Several hooks cover common cases: useNavigation, useRoute, useNavigationState, useFocusEffect, useIsFocused and useScrollToTop.

A new setOptions method on the navigation prop replaces static navigationOptions for many uses. It can be called at any time to set screen options from props, state or context without passing values through params, for example to add a header button that interacts with screen state.

Theming, types and debugging

  • Theming: a theme object with colors such as primary, background, card, text and border now restyles all navigators without extra code, replacing the previous light/dark-only support.
  • TypeScript: the library was rewritten in TypeScript, providing autocompletion and type-checking, plus JSDoc descriptions for built-in methods and options.
  • Redux DevTools: navigation actions and state appear in React Native Debugger or the Redux DevTools Extension, including time-travel debugging. Apps do not need to use Redux, and no extra setup is required.

Native options

A new native stack navigator uses native navigation primitives through react-native-screens, aimed at developers who want native feel and performance rather than the JavaScript-based stack. The Material top tab navigator also gains alternative pager backends based on react-native-viewpager (via react-native-tab-view-viewpager-adapter) and ScrollView (via ScrollPager from react-native-tab-view).

Smaller improvements

  • A revamped drawer navigator with easier sidebar customization
  • A simpler reset action that accepts the new state directly
  • More reliable focus and blur events
  • InteractionManager integration to defer work until animations finish
  • Safe area handling via react-native-safe-area-context

Upgrading

While concepts such as nesting remain, the new API is mostly incompatible with version 4. React Navigation 4 will continue to receive bug fixes and compatibility updates for new React Native versions, with its code living in the 4.x branch on GitHub. New projects are encouraged to start on version 5, and an upgrade guide is available.

Alpha users should note a few changes: replace @react-navigation/core imports with @react-navigation/native, rename NavigationNativeContainer to NavigationContainer (and the former NavigationContainer to BaseNavigationContainer), and review the deep linking configuration, whose format for nesting has changed.

Source: reactnavigation.org