• @react-navigation/core
• @react-navigation/native
• @react-navigation/stack
• @react-navigation/bottom-tabs
• @react-navigation/drawer
• @react-navigation/material-bottom-tabs
• @react-navigation/material-top-tabs

ParamList

To properly type the navigate function on the navigation prop, we need to pass in the full list of route names, as well as their corresponding params. We call this map a ParamList. Here’s an example of one:

type ChatParamList = {|
  ThreadList: void,
  MessageList: {| threadID: string |},
  ComposeThread: {| parentThreadID?: string |},
|};

Since the navigation prop can navigate to any screen in your app, even if it’s outside the current navigator, it’s important that each screen in your app is represented in the ParamList you pass in to your navigation props. Attempts to navigate to routes not specified in the ParamList will lead to type errors.

If your app dynamically generates routes, or if there are other reasons preventing you from statically typing all of your routes, you can specify “default” params for any unspecified routes using ParamListBase. These params will be treated as { +[key: string]: mixed, ... }.

import type { ParamListBase } from '@react-navigation/core';

type ChatParamList = {
  ...ParamListBase,
  ThreadList: void,
  MessageList: {| threadID: string |},
  ComposeThread: {| parentThreadID?: string |},
  ...
};

Typing navigators and screens

Here’s an example of how you might type a simple app that nests a StackNavigator within a BottomTabNavigator:

import {
  createBottomTabNavigator,
  type BottomTabNavigationProp,
} from '@react-navigation/bottom-tabs';
import {
  createStackNavigator,
  type StackNavigationProp,
} from '@react-navigation/stack';
import type { RouteProp } from '@react-navigation/native';

type TabParamList = {|
  Calendar: void,
  Chat: void,
  Friends: void,
|};
type ChatParamList = {|
  ThreadList: void,
  MessageList: {| threadID: string |},
  ComposeThread: {| parentThreadID?: string |},
|};
type GlobalParamList = {|
  ...TabParamList,
  ...ChatParamList,
|};
type NavigationRoute = RouteProp<
  GlobalParamList,
  $Keys<GlobalParamList>,
>;

// We limit the possible routes to TabParamList, but make sure to
// pass the GlobalParamList to the navigation prop so we can
// navigate to other navigators
type TabNavigationProp<
  RouteName: $Keys<TabParamList> = $Keys<TabParamList>,
> = BottomTabNavigationProp<GlobalParamList, RouteName>;

// We pass in a TabNavigationProp below that isn't constrained to a
// specific route. This is so we can type navigator props like
// screenOptions, which can be specified as a function that is
// passed a navigation prop
const Tab = createBottomTabNavigator<
  GlobalParamList,
  TabParamList,
  TabNavigationProp<>,
>();

type ChatNavigationProp<
  RouteName: $Keys<ChatParamList> = $Keys<ChatParamList>,
> = StackNavigationProp<GlobalParamList, RouteName>;

const Stack = createStackNavigator<
  GlobalParamList,
  ChatParamList,
  ChatNavigationProp<>,
>();

// Each individual screen should be typed with navigation and route
// props for a specific route, so that route.params and
// navigation.setParams can be typed correctly
function Calendar(props: {|
  navigation: TabNavigationProp<'Calendar'>,
  route: NavigationRoute<'Calendar'>,
|}) {
  [...]
}

[...]

// Finally we define the navigation structure using the navigators
// we're constructed
function Chat() {
  return (
    <Stack.Navigator>
      <Stack.Screen
        name="ThreadList"
        component={ThreadList}
      />
      <Stack.Screen
        name="MessageList"
        component={MessageList}
      />
      <Stack.Screen
        name="ComposeThread"
        component={ComposeThread}
      />
    </Stack.Navigator>
  );
}

function App() {
  return (
    <Tab.Navigator>
      <Tab.Screen
        name="Calendar"
        component={Calendar}
      />
      <Tab.Screen
        name="Chat"
        component={Chat}
      />
      <Tab.Screen
        name="Friends"
        component={Friends}
      />
    </Tab.Navigator>
  );
}

Custom navigators

Let’s start out with a simple custom stack navigator that uses the standard StackView component but specifies a custom router.

import {
  type StackAction,
  type StackNavigationProp,
  type ParamListBase,
  type Router,
  type StackRouterOptions,
  type StackNavigationState,
  type RouterConfigOptions,
  type StackOptions,
  type StackNavigationEventMap,
  type StackNavigatorProps,
  type ExtraStackNavigatorProps,
  StackRouter,
  CommonActions,
  createNavigatorFactory,
  useNavigationBuilder,
} from '@react-navigation/native';
import { StackView } from '@react-navigation/stack';

type ClearScreensAction = {|
  +type: 'CLEAR_SCREENS',
  +payload: {|
    +routeNames: $ReadOnlyArray<string>,
  |},
|};
type ChatRouterNavigationAction =
  | StackAction
  | ClearScreensAction;

type ChatRouterNavigationProp<
  ParamList: ParamListBase = ParamListBase,
  RouteName: string = string,
> = {|
  ...StackNavigationProp<ParamList, RouteName>,
  +clearScreens: (routeNames: $ReadOnlyArray<string>) => void,
  +goBackOnce: () => void,
|};

function ChatRouter(
  routerOptions: StackRouterOptions,
): Router<StackNavigationState, ChatRouterNavigationAction> {
  const {
    getStateForAction: baseGetStateForAction,
    actionCreators: baseActionCreators,
    ...rest
  } = StackRouter(routerOptions);
  return {
    ...rest,
    getStateForAction: (
      lastState: StackNavigationState,
      action: ChatRouterNavigationAction,
      options: RouterConfigOptions,
    ) => {
      if (action.type === 'CLEAR_SCREENS') {
        [...]
      } else {
        return baseGetStateForAction(lastState, action, options);
      }
    },
    actionCreators: {
      ...baseActionCreators,
      clearScreens: (routeNames: $ReadOnlyArray<string>) => ({
        type: 'CLEAR_SCREENS',
        payload: {
          routeNames,
        },
      }),
      goBackOnce: () => state => ({
        ...CommonActions.goBack(),
        target: state.key,
      }),
    },
  };
}

type ChatNavigatorProps = StackNavigatorProps<
  ChatRouterNavigationProp<>,
>;
function ChatNavigator({
  initialRouteName,
  children,
  screenOptions,
  ...rest
}: ChatNavigatorProps) {
  const { state, descriptors, navigation } = useNavigationBuilder(
    ChatRouter,
    {
      initialRouteName,
      children,
      screenOptions,
    },
  );
  return (
    <StackView
      {...rest}
      state={state}
      descriptors={descriptors}
      navigation={navigation}
    />
  );
}

const createChatNavigator = createNavigatorFactory<
  StackNavigationState,
  StackOptions,
  StackNavigationEventMap,
  ChatRouterNavigationProp<>,
  ExtraStackNavigatorProps,
>(ChatNavigator);

EventMap

Finally, let’s consider a fully custom navigator that doesn’t use any React Navigation UI components. In this case you will need to specify the screen options and the “event map” yourself.

The EventMap is a “synthetic” type, meaning it doesn’t actually type any values used in React Navigation. We use it to type the event objects passed to event listeners. It specifies two things: any custom data the event object will have, and whether the event.preventDefault() function will exist.

Consider the EventMap for BottomTabNavigator:

declare export type BottomTabNavigationEventMap = {|
  +state: {|
    +data: {| +state: TabNavigationState |},
    +canPreventDefault: false,
  |},
  +focus: {| +data: void, +canPreventDefault: false |},
  +blur: {| +data: void, +canPreventDefault: false |},
  +tabPress: {| +data: void, +canPreventDefault: true |},
  +tabLongPress: {| +data: void, +canPreventDefault: false |},
|};

Note that only the tabPress and tabLongPress events expose event.preventDefault(), and that only the state event has custom data.

Finally, let’s consider what a fully custom navigator that uses StackRouter for routing might look like:

import {
  type ParamListBase,
  type StackNavigationProp,
  type StackRouterOptions,
  type StackNavigationState,
  type StackAction,
  type NavigatorPropsBase,
  type ExtraNavigatorPropsBase,
  useNavigationBuilder,
  createNavigatorFactory,
} from '@react-navigation/state';

type CustomScreenOptions = {|
  +title: string,
|};
type CustomEventMap = {|
  +pressButton: {| +data: void, +canPreventDefault: false |},
|};

type CustomRouterNavigationProp<
  ParamList: ParamListBase = ParamListBase,
  RouteName: string = string,
> = {|
  ...StackNavigationProp<
    ParamList,
    RouteName,
    CustomScreenOptions,
    CustomEventMap,
  >,
  [...]
|};

function CustomRouter(
  routerOptions: StackRouterOptions,
): Router<StackNavigationState, StackAction> {
  [...]
}

type NavigatorProps = $Exact<NavigatorPropsBase<
  CustomScreenOptions,
  CustomRouterNavigationProp<>,
>>;

function CustomNavigator({
  initialRouteName,
  children,
  screenOptions,
}: Props) {
  const { state, descriptors, navigation } = useNavigationBuilder(
    CustomRouter,
    {
      initialRouteName,
      children,
      screenOptions,
    },
  );
  [...]
}

const createCustomNavigator = createNavigatorFactory<
  StackNavigationState,
  CustomScreenOptions,
  CustomEventMap,
  CustomRouterNavigationProp<>,
  ExtraNavigatorPropsBase,
>(CustomNavigator);

Thanks for reading! If you have any questions, you can try to reach me on the Flow Discord channel, or by creating an issue on the flow-typed GitHub repo and tagging @ashoat.