Skip to main content
Version: 8.x

Type checking with TypeScript

React Navigation can be configured to type-check screens and their params, as well as various other APIs using TypeScript. This provides better IntelliSense and type safety when working with React Navigation.

First, make sure you have the following configuration in your tsconfig.json under compilerOptions:

  • strict: true or strictNullChecks: true - Necessary for IntelliSense and type inference to work correctly.
  • moduleResolution: "bundler" - Necessary to resolve the types correctly and match the behavior of Metro and other bundlers.

Setting up the types​

There are 2 steps to configure TypeScript with the static API:

Specifying the root navigator's type​

For the type-inference to work, React Navigation needs to know the type of the root navigator in your app. To do this, you can declare a module augmentation for @react-navigation/native and extend the RootNavigator interface with the type of your root navigator.

const HomeTabs = createBottomTabNavigator({
  screens: {
    Feed: FeedScreen,
    Profile: ProfileScreen,
  },
});

const RootStack = createNativeStackNavigator({
  screens: {
    Home: HomeTabs,
  },
});

type RootStackType = typeof RootStack;

declare module '@react-navigation/native' {
  interface RootNavigator extends RootStackType {}
}

This is needed to type-check hooks such as useNavigation, useRoute, useNavigationState etc.

Specifying param types for screens​

After setting up the type for the root navigator, all we need to do is specify the type of params that our screens accept.

This can be done in 2 ways:

  1. The path pattern specified in the linking config (e.g. for path: 'profile/:userId', the type of route.params is { userId: string }). The type can be further customized by:

    • Using a parse function:

      linking: {
        path: 'profile/:userId',
        parse: {
          userId: (id) => parseInt(id, 10),
        },
      },

    • Using a Standard Schema:

      import { z } from 'zod';

      linking: {
        path: 'profile/:userId',
        parse: {
          userId: z.coerce.number(),
        },
      },

    The above examples would also make the type of route.params be { userId: number }. See passing params for the API and Parse function vs Standard Schema for the differences in type inference.

    This is the recommended way to specify params for screens that are accessible via deep linking or if your app runs on the Web, as it ensures that the types of params are consistent with the URL.

  2. The type annotation for the component specified in screen:

    import type { StaticScreenProps } from '@react-navigation/native';

    type ProfileParams = {
      userId: string;
    };

    function ProfileScreen({ route }: StaticScreenProps<ProfileParams>) {
      // ...
    }

    In the above example, the type of route.params is { userId: string } based on the type annotation in StaticScreenProps<ProfileParams>.

    If you aren't using the route object in the component, you can specify the props as _ to avoid unused variable warnings:

    function ProfileScreen(_: StaticScreenProps<ProfileParams>) {
      // ...
    }

If both screen and linking specify params, the final type of route.params is the intersection of both types.

This is how the complete example would look like:

const MyStack = createNativeStackNavigator({
  screens: {
    Profile: createNativeStackScreen({
      screen: ProfileScreen,
      linking: {
        path: 'profile/:userId',
        parse: {
          userId: (id) => parseInt(id, 10),
        },
      },
    }),
  },
});

Or with a Standard Schema:

import { z } from 'zod';

const MyStack = createNativeStackNavigator({
  screens: {
    Profile: createNativeStackScreen({
      screen: ProfileScreen,
      linking: {
        path: 'profile/:userId',
        parse: {
          userId: z.coerce.number(),
        },
      },
    }),
  },
});

If you have specified the params in linking, it's recommended to not specify them again in the component's props, and use useRoute('ScreenName') instead to get the correctly typed route object.

The createXScreen helper functions enable type inference in screen configuration callbacks like options, listeners, etc. Each navigator exports its own version of the helper function:

  • createNativeStackScreen from @react-navigation/native-stack
  • createStackScreen from @react-navigation/stack
  • createBottomTabScreen from @react-navigation/bottom-tabs
  • createDrawerScreen from @react-navigation/drawer
  • createMaterialTopTabScreen from @react-navigation/material-top-tabs

See Static configuration for more details.

Parse function vs Standard Schema​

Both parse functions and Standard Schemas infer param types from the parse config, but they differ in how they handle type inference for query params.

Path pattern params​

For params in path pattern, both approaches work the same way:

  • The return type of the function or the output type of the schema is used as the param type.
  • If the pattern includes the ? suffix, it's inferred as optional.

e.g. both of the following configs would make the type of route.params be { id: number }:

Parse function:

parse: {
  id: Number,
}

Standard Schema:

parse: {
  id: z.coerce.number(),
}

Query params​

Query params are inferred differently based on whether you use a parse function or a Standard Schema.

  • With a parse function, query params are always inferred as optional since they may not be present in the URL:

    parse: {
      sort: (value: string) => (value === 'new' ? 'new' : 'top'),
    }

    Here route.params are inferred as { sort?: 'new' | 'top' }.

  • With a Standard Schema, query params are inferred as required or optional based on the schema's output type:

    parse: {
      sort: z.string(),
    }

    Here route.params are inferred as { sort: string }.

    parse: {
      sort: z.string().optional(),
    }

    Here route.params are inferred as { sort?: string | undefined }.

Using typed hooks​

The useRoute, useNavigation, and useNavigationState hooks accept the name of the current screen or any parent screen where it's nested as an argument to infer the correct types.

Once the types are set up, these hooks are automatically typed based on the name of the screen passed to them.

With useRoute:

function ProfileScreen() {
  const route = useRoute('Profile');

  // The params are correctly typed here
  const { userId } = route.params;

  // ...
}

With useNavigation:

function ProfileScreen() {
  const navigation = useNavigation('Profile');

  // Helpers like `jumpTo` are correctly typed here
  navigation.jumpTo('Feed');

  // ...
}

With useNavigationState:

function ProfileScreen() {
  const focusedRouteName = useNavigationState(
    'Profile',
    // The state is correctly typed here
    (state) => state.routes[state.index].name
  );

  // The `focusedRouteName` type is one of the route names
  // defined in the navigator where `Profile` is defined
  console.log(focusedRouteName);

  // ...
}

It's also possible to use these hooks without specifying the screen name - which can be useful in re-usable components that can be used across multiple screens. In this case, different things happen based on the hook.

The useRoute hook returns a union of all routes in the app, and can be narrowed down using type guards:

function Header() {
  const route = useRoute();

  // The route is a union of all routes in the app
  console.log(route.name);

  // It's possible to narrow down the type using type guards
  if (route.name === 'Profile') {
    // Here route.params is correctly typed
    const { userId } = route.params;
  }

  // ...
}

The useNavigation hook returns a generic navigation object that refers to the root navigator. This means that any navigation actions can be called as if they are used in a screen of the root navigator:

function Header() {
  const navigation = useNavigation();

  // A generic navigation object that refers to the root navigator
  navigation.navigate('Profile', { userId: '123' });

  // ...
}

The useNavigationState hook returns a generic navigation state without any navigator-specific types:

function Header() {
  const focusedRouteName = useNavigationState((state) => {
    // The state is a generic navigation state
    return state.routes[state.index].name;
  });

  // The `focusedRouteName` type is `string`
  console.log(focusedRouteName);

  // ...
}

Nesting a dynamic navigator​

If you render a dynamic navigator inside a static navigator, see Mixing Static & Dynamic APIs for the additional typing and linking configuration needed for the nested navigator.