@react-navigation/core

@react-navigation/core

Version 7.8.5
Published 20 days ago
683 kB
7 dependencies
MIT license

Install

npm i @react-navigation/core

yarn add @react-navigation/core

pnpm add @react-navigation/core

Overview

Core utilities for building navigators

Index

Variables

BaseNavigationContainer
CurrentRenderContext
NavigationContainerRefContext
NavigationContext
NavigationHelpersContext
NavigationRouteContext
PreventRemoveContext
ThemeContext

Classes

PrivateValueStore
- ''

Variables

variable BaseNavigationContainer

const BaseNavigationContainer: React.ForwardRefExoticComponent<any>;

Container component which holds the navigation state. This should be rendered at the root wrapping the whole app.
Parameter
props.initialState Initial state object for the navigation tree.
Parameter
props.onReady Callback which is called after the navigation tree mounts.
Parameter
props.onStateChange Callback which is called with the latest navigation state when it changes.
Parameter
props.onUnhandledAction Callback which is called when an action is not handled.
Parameter
props.theme Theme object for the UI elements.
Parameter
props.children Child elements to render the content.
Parameter
props.ref Ref object which refers to the navigation object containing helper methods.

variable CurrentRenderContext

const CurrentRenderContext: React.Context<{ options?: object }>;

Context which holds the values for the current navigation tree. Intended for use in SSR. This is not safe to use on the client.

variable NavigationContainerRefContext

const NavigationContainerRefContext: React.Context<
    NavigationContainerRef<ParamListBase>
>;

Context which holds the route prop for a screen.

variable NavigationContext

const NavigationContext: React.Context<
    NavigationProp<
        ParamListBase,
        string,
        undefined,
        NavigationState<ParamList>,
        {},
        {}
    >
>;

Context which holds the navigation prop for a screen.

variable NavigationHelpersContext

const NavigationHelpersContext: React.Context<NavigationHelpers<ParamListBase, {}>>;

Context which holds the navigation helpers of the parent navigator. Navigators should use this context in their view component.

variable NavigationRouteContext

const NavigationRouteContext: React.Context<any>;

Context which holds the route prop for a screen.

variable PreventRemoveContext

const PreventRemoveContext: React.Context<{
    preventedRoutes: PreventedRoutes;
    setPreventRemove: (id: string, routeKey: string, preventRemove: boolean) => void;
}>;

variable ThemeContext

const ThemeContext: React.Context<ReactNavigation.Theme>;

Functions

function createComponentForStaticNavigation

createComponentForStaticNavigation: (
    tree: StaticNavigation<any, any, any>,
    displayName: string
) => React.ComponentType<{}>;

Create a component that renders a navigator based on the static configuration.
Parameter tree
Static navigation config.
Parameter displayName
Name of the component to be displayed in React DevTools.
Returns
A component which renders the navigator.

function createNavigationContainerRef

createNavigationContainerRef: <
    ParamList extends {} = ReactNavigation.RootParamList
>() => NavigationContainerRefWithCurrent<ParamList>;

function createNavigatorFactory

createNavigatorFactory: (
    Navigator: React.ComponentType<any>
) => (config?: any) => any;

Higher order component to create a Navigator and Screen pair. Custom navigators should wrap the navigator component in createNavigator before exporting.
Parameter Navigator
The navigator component to wrap.
Returns
Factory method to create a Navigator and Screen pair.

function createPathConfigForStaticNavigation

createPathConfigForStaticNavigation: (
    tree: TreeForPathConfig,
    options?: { initialRouteName?: string },
    auto?: boolean
) => {} | undefined;

Create a path config object from a static navigation config for deep linking.
Parameter tree
Static navigation config.
Parameter options
Additional options from linking.config.
Parameter auto
Whether to automatically generate paths for leaf screens.
Returns
Path config object to use in linking config.
Example 1
const config = { screens: { Home: { screens: createPathConfigForStaticNavigation(HomeTabs), }, }, };

function findFocusedRoute

findFocusedRoute: (state: InitialState) => Result;

function getActionFromState

getActionFromState: (
    state: PartialState<NavigationState>,
    options?: Options
) => NavigateAction<NavigationState> | CommonActions.Action | undefined;

function getFocusedRouteNameFromRoute

getFocusedRouteNameFromRoute: (route: Route<string>) => string | undefined;

function getPathFromState

getPathFromState: <ParamList extends {}>(
    state: State,
    options?: Options<ParamList>
) => string;

Utility to serialize a navigation state object to a path string.

Parameter state

Navigation state to serialize.

Parameter options

Extra options to fine-tune how to serialize the path.

Returns

Path representing the state, e.g. /foo/bar?count=42.

Example 1

getPathFromState(
  {
    routes: [
      {
        name: 'Chat',
        params: { author: 'Jane', id: 42 },
      },
    ],
  },
  {
    screens: {
      Chat: {
        path: 'chat/:author/:id',
        stringify: { author: author => author.toLowerCase() }
      }
    }
  }
)

function getStateFromPath

getStateFromPath: <ParamList extends {}>(
    path: string,
    options?: Options<ParamList>
) => ResultState | undefined;

Utility to parse a path string to initial state object accepted by the container. This is useful for deep linking when we need to handle the incoming URL.
Parameter path
Path string to parse and convert, e.g. /foo/bar?count=42.
Parameter options
Extra options to fine-tune how to parse the path.
Example 1
getStateFromPath( '/chat/jane/42', { screens: { Chat: { path: 'chat/:author/:id', parse: { id: Number } } } } )

function NavigationIndependentTree

NavigationIndependentTree: ({ children }: { children: React.ReactNode }) => any;

Component to make the child navigation container independent of parent containers.

function PreventRemoveProvider

PreventRemoveProvider: ({ children }: Props) => any;

Component used for managing which routes have to be prevented from removal in native-stack.

function ThemeProvider

ThemeProvider: ({ value, children }: Props) => any;

function useFocusEffect

useFocusEffect: (effect: EffectCallback) => void;

Hook to run an effect in a focused screen, similar to React.useEffect. This can be used to perform side-effects such as fetching data or subscribing to events. The passed callback should be wrapped in React.useCallback to avoid running the effect too often.
Parameter callback
Memoized callback containing the effect, should optionally return a cleanup function.

function useIsFocused

useIsFocused: () => boolean;

Hook to get the current focus state of the screen. Returns a true if screen is focused, otherwise false. This can be used if a component needs to render something based on the focus state.

function useNavigation

useNavigation: <
    T = Omit<
        NavigationProp<
            ReactNavigation.RootParamList,
            never,
            undefined,
            NavigationState<ParamList>,
            {},
            {}
        >,
        'getState'
    > & { getState(): NavigationState | undefined }
>() => T;

Hook to access the navigation prop of the parent screen anywhere.
Returns
Navigation prop of the parent screen.

function useNavigationBuilder

useNavigationBuilder: <
    State extends NavigationState,
    RouterOptions extends DefaultRouterOptions,
    ActionHelpers extends Record<string, (...args: any) => void>,
    ScreenOptions extends {},
    EventMap extends Record<string, any>
>(
    createRouter: RouterFactory<State, NavigationAction, RouterOptions>,
    options: DefaultNavigatorOptions<
        ParamListBase,
        string | undefined,
        State,
        ScreenOptions,
        EventMap,
        any
    > &
        RouterOptions
) => {
    state: State;
    navigation: {
        dispatch(
            action:
                | Readonly<{
                      type: string;
                      payload?: object;
                      source?: string;
                      target?: string;
                  }>
                | ((
                      state: Readonly<
                          Readonly<{
                              key: string;
                              index: number;
                              routeNames: string[];
                              history?: unknown[];
                              routes: import('@react-navigation/routers').NavigationRoute<
                                  ParamListBase,
                                  string
                              >[];
                              type: string;
                              stale: false;
                          }>
                      >
                  ) => NavigationAction)
        ): void;
        navigate<RouteName extends string>(
            ...args: RouteName extends unknown
                ? [
                      screen: RouteName,
                      params?: object,
                      options?: { merge?: boolean; pop?: boolean }
                  ]
                : never
        ): void;
        navigate<RouteName extends string>(
            options: RouteName extends unknown
                ? {
                      name: RouteName;
                      params: object | undefined;
                      path?: string;
                      merge?: boolean;
                      pop?: boolean;
                  }
                : never
        ): void;
        navigateDeprecated<RouteName extends string>(
            ...args: RouteName extends unknown
                ? [screen: RouteName, params?: object]
                : never
        ): void;
        navigateDeprecated<RouteName extends string>(
            options: RouteName extends unknown
                ? { name: RouteName; params: object | undefined; merge?: boolean }
                : never
        ): void;
        preload<RouteName extends string>(
            ...args: RouteName extends unknown
                ? [screen: RouteName, params?: object]
                : never
        ): void;
        reset(
            state:
                | Readonly<{
                      key: string;
                      index: number;
                      routeNames: string[];
                      history?: unknown[];
                      routes: import('@react-navigation/routers').NavigationRoute<
                          ParamListBase,
                          string
                      >[];
                      type: string;
                      stale: false;
                  }>
                | PartialState<
                      Readonly<{
                          key: string;
                          index: number;
                          routeNames: string[];
                          history?: unknown[];
                          routes: import('@react-navigation/routers').NavigationRoute<
                              ParamListBase,
                              string
                          >[];
                          type: string;
                          stale: false;
                      }>
                  >
        ): void;
        goBack(): void;
        isFocused(): boolean;
        canGoBack(): boolean;
        getId(): string | undefined;
        getParent<T = NavigationHelpers<ParamListBase, {}>>(id?: string): T;
        getState(): Readonly<{
            key: string;
            index: number;
            routeNames: string[];
            history?: unknown[];
            routes: import('@react-navigation/routers').NavigationRoute<
                ParamListBase,
                string
            >[];
            type: string;
            stale: false;
        }>;
        setStateForNextRouteNamesChange(
            state:
                | Readonly<{
                      key: string;
                      index: number;
                      routeNames: string[];
                      history?: unknown[];
                      routes: import('@react-navigation/routers').NavigationRoute<
                          ParamListBase,
                          string
                      >[];
                      type: string;
                      stale: false;
                  }>
                | PartialState<
                      Readonly<{
                          key: string;
                          index: number;
                          routeNames: string[];
                          history?: unknown[];
                          routes: import('@react-navigation/routers').NavigationRoute<
                              ParamListBase,
                              string
                          >[];
                          type: string;
                          stale: false;
                      }>
                  >
        ): void;
    } & PrivateValueStore<[ParamListBase, unknown, unknown]> &
        EventEmitter<EventMap> & {
            setParams<RouteName extends string>(
                params: Partial<object | undefined>
            ): void;
        } & ActionHelpers;
    describe: (
        route: Route<Extract<RouteName, string>, ParamList[RouteName]>,
        placeholder: boolean
    ) => Descriptor<
        ScreenOptions,
        Omit<
            {
                dispatch(
                    action:
                        | Readonly<{
                              type: string;
                              payload?: object;
                              source?: string;
                              target?: string;
                          }>
                        | ((state: Readonly<State>) => NavigationAction)
                ): void;
                navigate<RouteName extends string>(
                    ...args: RouteName extends unknown
                        ? [
                              screen: RouteName,
                              params?: object,
                              options?: { merge?: boolean; pop?: boolean }
                          ]
                        : never
                ): void;
                navigate<RouteName extends string>(
                    options: RouteName extends unknown
                        ? {
                              name: RouteName;
                              params: object | undefined;
                              path?: string;
                              merge?: boolean;
                              pop?: boolean;
                          }
                        : never
                ): void;
                navigateDeprecated<RouteName extends string>(
                    ...args: RouteName extends unknown
                        ? [screen: RouteName, params?: object]
                        : never
                ): void;
                navigateDeprecated<RouteName extends string>(
                    options: RouteName extends unknown
                        ? {
                              name: RouteName;
                              params: object | undefined;
                              merge?: boolean;
                          }
                        : never
                ): void;
                preload<RouteName extends string>(
                    ...args: RouteName extends unknown
                        ? [screen: RouteName, params?: object]
                        : never
                ): void;
                reset(state: State | PartialState<State>): void;
                goBack(): void;
                isFocused(): boolean;
                canGoBack(): boolean;
                getId(): string | undefined;
                getParent<T = NavigationHelpers<ParamListBase, {}>>(id?: string): T;
                getState(): State;
                setStateForNextRouteNamesChange(
                    state: State | PartialState<State>
                ): void;
            } & PrivateValueStore<[ParamListBase, unknown, unknown]>,
            'getParent'
        > & {
            getParent<
                T = NavigationProp<
                    ParamListBase,
                    string,
                    undefined,
                    Readonly<{
                        key: string;
                        index: number;
                        routeNames: string[];
                        history?: unknown[];
                        routes: import('@react-navigation/routers').NavigationRoute<
                            ParamListBase,
                            string
                        >[];
                        type: string;
                        stale: false;
                    }>,
                    {},
                    {}
                >
            >(
                id?: string | undefined
            ): T;
            setParams(params: Partial<object | undefined>): void;
            setOptions(options: Partial<ScreenOptions>): void;
        } & EventConsumer<EventMap & EventMapCore<State>> &
            PrivateValueStore<[ParamListBase, string, EventMap]> &
            ActionHelpers,
        Route<Extract<RouteName, string>, ParamList[RouteName]>
    >;
    descriptors: Record<
        string,
        Descriptor<
            ScreenOptions,
            Omit<
                {
                    dispatch(
                        action:
                            | Readonly<{
                                  type: string;
                                  payload?: object;
                                  source?: string;
                                  target?: string;
                              }>
                            | ((state: Readonly<State>) => NavigationAction)
                    ): void;
                    navigate<RouteName extends string>(
                        ...args: RouteName extends unknown
                            ? [
                                  screen: RouteName,
                                  params?: object,
                                  options?: { merge?: boolean; pop?: boolean }
                              ]
                            : never
                    ): void;
                    navigate<RouteName extends string>(
                        options: RouteName extends unknown
                            ? {
                                  name: RouteName;
                                  params: object | undefined;
                                  path?: string;
                                  merge?: boolean;
                                  pop?: boolean;
                              }
                            : never
                    ): void;
                    navigateDeprecated<RouteName extends string>(
                        ...args: RouteName extends unknown
                            ? [screen: RouteName, params?: object]
                            : never
                    ): void;
                    navigateDeprecated<RouteName extends string>(
                        options: RouteName extends unknown
                            ? {
                                  name: RouteName;
                                  params: object | undefined;
                                  merge?: boolean;
                              }
                            : never
                    ): void;
                    preload<RouteName extends string>(
                        ...args: RouteName extends unknown
                            ? [screen: RouteName, params?: object]
                            : never
                    ): void;
                    reset(state: State | PartialState<State>): void;
                    goBack(): void;
                    isFocused(): boolean;
                    canGoBack(): boolean;
                    getId(): string | undefined;
                    getParent<T = NavigationHelpers<ParamListBase, {}>>(
                        id?: string
                    ): T;
                    getState(): State;
                    setStateForNextRouteNamesChange(
                        state: State | PartialState<State>
                    ): void;
                } & PrivateValueStore<[ParamListBase, unknown, unknown]>,
                'getParent'
            > & {
                getParent<
                    T = NavigationProp<
                        ParamListBase,
                        string,
                        undefined,
                        Readonly<{
                            key: string;
                            index: number;
                            routeNames: string[];
                            history?: unknown[];
                            routes: import('@react-navigation/routers').NavigationRoute<
                                ParamListBase,
                                string
                            >[];
                            type: string;
                            stale: false;
                        }>,
                        {},
                        {}
                    >
                >(
                    id?: string | undefined
                ): T;
                setParams(params: Partial<object | undefined>): void;
                setOptions(options: Partial<ScreenOptions>): void;
            } & EventConsumer<EventMap & EventMapCore<State>> &
                PrivateValueStore<[ParamListBase, string, EventMap]> &
                ActionHelpers,
            Route<Extract<RouteName, string>, ParamList[RouteName]>
        >
    >;
    NavigationContent: ({ children }: { children: React.ReactNode }) => any;
};

Hook for building navigators.
Parameter createRouter
Factory method which returns router object.
Parameter options
Options object containing children and additional options for the router.
Returns
An object containing state, navigation, descriptors objects.

function useNavigationContainerRef

useNavigationContainerRef: <
    ParamList extends {} = ReactNavigation.RootParamList
>() => NavigationContainerRefWithCurrent<ParamList>;

function useNavigationIndependentTree

useNavigationIndependentTree: () => boolean;

function useNavigationState

useNavigationState: <ParamList extends ParamListBase, T>(
    selector: Selector<ParamList, T>
) => T;

Hook to get a value from the current navigation state using a selector.
Parameter selector
Selector function to get a value from the state.

function usePreventRemove

usePreventRemove: (
    preventRemove: boolean,
    callback: (options: { data: { action: NavigationAction } }) => void
) => void;

Hook to prevent screen from being removed. Can be used to prevent users from leaving the screen.
Parameter preventRemove
Boolean indicating whether to prevent screen from being removed.
Parameter callback
Function which is executed when screen was prevented from being removed.

function usePreventRemoveContext

usePreventRemoveContext: () => {
    preventedRoutes: import('./PreventRemoveContext').PreventedRoutes;
    setPreventRemove: (id: string, routeKey: string, preventRemove: boolean) => void;
};

function useRoute

useRoute: <
    T extends Route<Extract<RouteName, string>, ParamList[RouteName]>
>() => T;

Hook to access the route prop of the parent screen anywhere.
Returns
Route prop of the parent screen.

function useStateForPath

useStateForPath: () =>
    | import('./NavigationFocusedRouteStateContext').FocusedRouteState
    | undefined;

Hook to get a minimal state representation for the current route. The returned state can be used with getPathFromState to build a path.
Returns
Minimal state to build a path for the current route.

function useTheme

useTheme: () => ReactNavigation.Theme;

function validatePathConfig

validatePathConfig: (config: unknown, root?: boolean) => void;

Classes

class PrivateValueStore

class PrivateValueStore<T extends [any, any, any]> {}

property ''

protected ''?: [any, any, any];

UGLY HACK! DO NOT USE THE TYPE!!!
TypeScript requires a type to be used to be able to infer it. The type should exist as its own without any operations such as union. So we need to figure out a way to store this type in a property. The problem with a normal property is that it shows up in intelliSense. Adding private keyword works, but the annotation is stripped away in declaration. Turns out if we use an empty string, it doesn't show up in intelliSense.

Type Aliases

type CompositeNavigationProp

type CompositeNavigationProp<
    A extends NavigationProp<ParamListBase, string, any, any, any>,
    B extends NavigationHelpersCommon<ParamListBase, any>
> = Omit<A & B, keyof NavigationProp<any>> &
    NavigationProp<
        /**
         * Param list from both navigation objects needs to be combined
         * For example, we should be able to navigate to screens in both A and B
         */
        (A extends NavigationHelpersCommon<infer T> ? T : never) &
            (B extends NavigationHelpersCommon<infer U> ? U : never),
        /**
         * The route name should refer to the route name specified in the first type
         * Ideally it should work for any of them, but it's not possible to infer that way
         */
        A extends NavigationProp<any, infer R> ? R : string,
        /**
         * ID from both navigation objects needs to be combined for `getParent`
         */
        | (A extends NavigationProp<any, any, infer I> ? I : never)
        | (B extends NavigationProp<any, any, infer J> ? J : never),
        /**
         * The type of state should refer to the state specified in the first type
         */
        A extends NavigationProp<any, any, any, infer S> ? S : NavigationState,
        /**
         * Screen options should refer to the options specified in the first type
         */
        A extends NavigationProp<any, any, any, any, infer O> ? O : {},
        /**
         * Event consumer config should refer to the config specified in the first type
         * This allows typechecking `addListener`/`removeListener`
         */
        A extends NavigationProp<any, any, any, any, any, infer E> ? E : {}
    >;

type CompositeScreenProps

type CompositeScreenProps<
    A extends {
        navigation: NavigationProp<
            ParamListBase,
            string,
            string | undefined,
            any,
            any,
            any
        >;
        route: RouteProp<ParamListBase>;
    },
    B extends {
        navigation: NavigationHelpersCommon<any, any>;
    }
> = {
    navigation: CompositeNavigationProp<A['navigation'], B['navigation']>;
    route: A['route'];
};

type DefaultNavigatorOptions

type DefaultNavigatorOptions<
    ParamList extends ParamListBase,
    NavigatorID extends string | undefined,
    State extends NavigationState,
    ScreenOptions extends {},
    EventMap extends EventMapBase,
    Navigation
> = DefaultRouterOptions<Keyof<ParamList>> & {
    /**
     * Children React Elements to extract the route configuration from.
     * Only `Screen`, `Group` and `React.Fragment` are supported as children.
     */
    children: React.ReactNode;
    /**
     * Layout for the navigator.
     * Useful for wrapping with a component with access to navigator's state and options.
     */
    layout?: (props: {
        state: State;
        navigation: NavigationHelpers<ParamList>;
        descriptors: Record<
            string,
            Descriptor<
                ScreenOptions,
                NavigationProp<
                    ParamList,
                    keyof ParamList,
                    string | undefined,
                    State,
                    ScreenOptions,
                    EventMap
                >,
                RouteProp<ParamList>
            >
        >;
        children: React.ReactNode;
    }) => React.ReactElement;
    /**
     * Event listeners for all the screens in the navigator.
     */
    screenListeners?:
        | ScreenListeners<State, EventMap>
        | ((props: {
              route: RouteProp<ParamList>;
              navigation: Navigation;
          }) => ScreenListeners<State, EventMap>);
    /**
     * Default options for all screens under this navigator.
     */
    screenOptions?:
        | ScreenOptions
        | ((props: {
              route: RouteProp<ParamList>;
              navigation: Navigation;
              theme: ReactNavigation.Theme;
          }) => ScreenOptions);
    /**
     * Layout for all screens under this navigator.
     */
    screenLayout?: (props: {
        route: RouteProp<ParamList, keyof ParamList>;
        navigation: Navigation;
        theme: ReactNavigation.Theme;
        children: React.ReactElement;
    }) => React.ReactElement;
    /**
     * A function returning overrides for the underlying router used by the navigator.
     * The overrides will be shallow merged onto the original router.
     * It receives the original router as an argument to the function.
     *
     * This must be a pure function and cannot reference outside dynamic variables.
     */
    UNSTABLE_router?: <Action extends NavigationAction>(
        original: Router<State, Action>
    ) => Partial<Router<State, Action>>;
} & (NavigatorID extends string
        ? {
              /**
               * Optional ID for the navigator. Can be used with `navigation.getParent(id)` to refer to a parent.
               */
              id: NavigatorID;
          }
        : {
              id?: undefined;
          });

type Descriptor

type Descriptor<
    ScreenOptions extends {},
    Navigation extends NavigationProp<any, any, any, any, any, any>,
    Route extends RouteProp<any, any>
> = {
    /**
     * Render the component associated with this route.
     */
    render(): React.JSX.Element;
    /**
     * Options for the route.
     */
    options: ScreenOptions;
    /**
     * Route object for the screen
     */
    route: Route;
    /**
     * Navigation object for the screen
     */
    navigation: Navigation;
};

type EventArg

type EventArg<
    EventName,
    CanPreventDefault extends boolean | undefined = false,
    Data = undefined
> = {
    /**
     * Type of the event (e.g. `focus`, `blur`)
     */
    readonly type: EventName;
    readonly target?: string;
} & (CanPreventDefault extends true
    ? {
          /**
           * Whether `event.preventDefault()` was called on this event object.
           */
          readonly defaultPrevented: boolean;
          /**
           * Prevent the default action which happens on this event.
           */
          preventDefault(): void;
      }
    : {}) &
    (undefined extends Data
        ? {
              readonly data?: Readonly<Data>;
          }
        : {
              readonly data: Readonly<Data>;
          });

type EventConsumer

type EventConsumer<EventMap extends EventMapBase> = {
    /**
     * Subscribe to events from the parent navigator.
     *
     * @param type Type of the event (e.g. `focus`, `blur`)
     * @param callback Callback listener which is executed upon receiving the event.
     */
    addListener<EventName extends Keyof<EventMap>>(
        type: EventName,
        callback: EventListenerCallback<EventMap, EventName>
    ): () => void;
    removeListener<EventName extends Keyof<EventMap>>(
        type: EventName,
        callback: EventListenerCallback<EventMap, EventName>
    ): void;
};

type EventEmitter

type EventEmitter<EventMap extends EventMapBase> = {
    /**
     * Emit an event to child screens.
     *
     * @param options.type Type of the event (e.g. `focus`, `blur`)
     * @param [options.data] Optional information regarding the event.
     * @param [options.target] Key of the target route which should receive the event.
     * If not specified, all routes receive the event.
     */
    emit<EventName extends Keyof<EventMap>>(
        options: {
            type: EventName;
            target?: string;
        } & (EventMap[EventName]['canPreventDefault'] extends true
            ? {
                  canPreventDefault: true;
              }
            : {}) &
            (undefined extends EventMap[EventName]['data']
                ? {
                      data?: EventMap[EventName]['data'];
                  }
                : {
                      data: EventMap[EventName]['data'];
                  })
    ): EventArg<
        EventName,
        EventMap[EventName]['canPreventDefault'],
        EventMap[EventName]['data']
    >;
};

type EventListenerCallback

type EventListenerCallback<
    EventMap extends EventMapBase,
    EventName extends keyof EventMap,
    EventCanPreventDefault extends
        | boolean
        | undefined = EventMap[EventName]['canPreventDefault']
> = (
    e: EventArg<
        EventName,
        undefined extends EventCanPreventDefault ? false : EventCanPreventDefault,
        EventMap[EventName]['data']
    >
) => void;

type EventMapBase

type EventMapBase = Record<
    string,
    {
        data?: any;
        canPreventDefault?: boolean;
    }
>;

type EventMapCore

type EventMapCore<State extends NavigationState> = {
    focus: {
        data: undefined;
    };
    blur: {
        data: undefined;
    };
    state: {
        data: {
            state: State;
        };
    };
    beforeRemove: {
        data: {
            action: NavigationAction;
        };
        canPreventDefault: true;
    };
};

type NavigationContainerEventMap

type NavigationContainerEventMap = {
    /**
     * Event that fires when the navigation container is ready to be used.
     */
    ready: {
        data: undefined;
    };
    /**
     * Event that fires when the navigation state changes.
     */
    state: {
        data: {
            /**
             * The updated state object after the state change.
             */
            state: NavigationState | PartialState<NavigationState> | undefined;
        };
    };
    /**
     * Event that fires when current options changes.
     */
    options: {
        data: {
            options: object;
        };
    };
    /**
     * Event that fires when an action is dispatched.
     * Only intended for debugging purposes, don't use it for app logic.
     * This event will be emitted before state changes have been applied.
     */
    __unsafe_action__: {
        data: {
            /**
             * The action object that was dispatched.
             */
            action: NavigationAction;
            /**
             * Whether the action was a no-op, i.e. resulted any state changes.
             */
            noop: boolean;
            /**
             * Stack trace of the action, this will only be available during development.
             */
            stack: string | undefined;
        };
    };
};

type NavigationContainerProps

type NavigationContainerProps = {
    /**
     * Initial navigation state for the child navigators.
     */
    initialState?: InitialState;
    /**
     * Callback which is called with the latest navigation state when it changes.
     */
    onStateChange?: (state: Readonly<NavigationState> | undefined) => void;
    /**
     * Callback which is called after the navigation tree mounts.
     */
    onReady?: () => void;
    /**
     * Callback which is called when an action is not handled.
     */
    onUnhandledAction?: (action: Readonly<NavigationAction>) => void;
    /**
     * Whether child navigator should handle a navigation action.
     * The child navigator needs to be mounted before it can handle the action.
     * Defaults to `false`.
     *
     * This will be removed in the next major release.
     *
     * @deprecated Use nested navigation API instead
     */
    navigationInChildEnabled?: boolean;
    /**
     * Theme object for the UI elements.
     */
    theme?: ReactNavigation.Theme;
    /**
     * Children elements to render.
     */
    children: React.ReactNode;
};

type NavigationContainerRef

type NavigationContainerRef<ParamList extends {}> = NavigationHelpers<ParamList> &
    EventConsumer<NavigationContainerEventMap> & {
        /**
         * Reset the navigation state of the root navigator to the provided state.
         *
         * @param state Navigation state object.
         */
        resetRoot(state?: PartialState<NavigationState> | NavigationState): void;
        /**
         * Get the rehydrated navigation state of the navigation tree.
         */
        getRootState(): NavigationState;
        /**
         * Get the currently focused navigation route.
         */
        getCurrentRoute(): MaybeParamListRoute<ParamList> | undefined;
        /**
         * Get the currently focused route's options.
         */
        getCurrentOptions(): object | undefined;
        /**
         * Whether the navigation container is ready to handle actions.
         */
        isReady(): boolean;
        /**
         * Stub function for setOptions on navigation object for use with useNavigation.
         */
        setOptions(): never;
        /**
         * Stub function for getParent on navigation object for use with useNavigation.
         */
        getParent(): undefined;
    };

type NavigationContainerRefWithCurrent

type NavigationContainerRefWithCurrent<ParamList extends {}> =
    NavigationContainerRef<ParamList> & {
        current: NavigationContainerRef<ParamList> | null;
    };

type NavigationHelpers

type NavigationHelpers<
    ParamList extends ParamListBase,
    EventMap extends EventMapBase = {}
> = NavigationHelpersCommon<ParamList> &
    EventEmitter<EventMap> & {
        /**
         * Update the param object for the route.
         * The new params will be shallow merged with the old one.
         *
         * @param params Params object for the current route.
         */
        setParams<RouteName extends keyof ParamList>(
            params: Partial<ParamList[RouteName]>
        ): void;
    };

type NavigationListBase

type NavigationListBase<ParamList extends ParamListBase> = {
    [RouteName in keyof ParamList]: unknown;
};

type NavigationProp

type NavigationProp<
    ParamList extends {},
    RouteName extends keyof ParamList = Keyof<ParamList>,
    NavigatorID extends string | undefined = undefined,
    State extends NavigationState = NavigationState<ParamList>,
    ScreenOptions extends {} = {},
    EventMap extends EventMapBase = {}
> = Omit<NavigationHelpersCommon<ParamList, State>, 'getParent'> & {
    /**
     * Returns the navigation prop from a parent navigator based on the ID.
     * If an ID is provided, the navigation prop from the parent navigator with matching ID (including current) will be returned.
     * If no ID is provided, the navigation prop from the immediate parent navigator will be returned.
     *
     * @param id Optional ID of a parent navigator.
     */
    getParent<T = NavigationProp<ParamListBase> | undefined>(id?: NavigatorID): T;
    /**
     * Update the param object for the route.
     * The new params will be shallow merged with the old one.
     *
     * @param params Params object for the current route.
     */
    setParams(
        params: ParamList[RouteName] extends undefined
            ? undefined
            : Partial<ParamList[RouteName]>
    ): void;
    /**
     * Update the options for the route.
     * The options object will be shallow merged with default options object.
     *
     * @param update Options object or a callback which takes the options from navigator config and returns a new options object.
     */
    setOptions(options: Partial<ScreenOptions>): void;
} & EventConsumer<EventMap & EventMapCore<State>> &
    PrivateValueStore<[ParamList, RouteName, EventMap]>;

type NavigatorScreenParams

type NavigatorScreenParams<ParamList extends {}> =
    | {
          screen?: never;
          params?: never;
          initial?: never;
          pop?: never;
          path?: string;
          state: PartialState<NavigationState> | NavigationState | undefined;
      }
    | {
          [RouteName in keyof ParamList]: undefined extends ParamList[RouteName]
              ? {
                    screen: RouteName;
                    params?: ParamList[RouteName];
                    initial?: boolean;
                    path?: string;
                    pop?: boolean;
                    state?: never;
                }
              : {
                    screen: RouteName;
                    params: ParamList[RouteName];
                    initial?: boolean;
                    path?: string;
                    pop?: boolean;
                    state?: never;
                };
      }[keyof ParamList];

type NavigatorTypeBag

type NavigatorTypeBag<
    ParamList extends ParamListBase,
    NavigatorID extends string | undefined,
    State extends NavigationState,
    ScreenOptions extends {},
    EventMap extends EventMapBase,
    NavigationList extends NavigationListBase<ParamList>,
    Navigator extends React.ComponentType<any>
> = {
    ParamList: ParamList;
    NavigatorID: NavigatorID;
    State: State;
    ScreenOptions: ScreenOptions;
    EventMap: EventMap;
    NavigationList: NavigationList;
    Navigator: Navigator;
};

type NavigatorTypeBagBase

type NavigatorTypeBagBase = {
    ParamList: {};
    NavigatorID: string | undefined;
    State: NavigationState;
    ScreenOptions: {};
    EventMap: {};
    NavigationList: NavigationListBase<ParamListBase>;
    Navigator: React.ComponentType<any>;
};

type ParamListRoute

type ParamListRoute<ParamList extends ParamListBase> = {
    [RouteName in keyof ParamList]: NavigatorScreenParams<{}> extends ParamList[RouteName]
        ? NotUndefined<ParamList[RouteName]> extends NavigatorScreenParams<infer T>
            ? ParamListRoute<T>
            : Route<Extract<RouteName, string>, ParamList[RouteName]>
        : Route<Extract<RouteName, string>, ParamList[RouteName]>;
}[keyof ParamList];

type PathConfig

type PathConfig<ParamList extends {}> = Partial<PathConfigAlias> & {
    /**
     * An object mapping the param name to a function which converts the param value to a string.
     * By default, all params are converted to strings using `String(value)`.
     *
     * @example
     * ```js
     * stringify: {
     *   date: (value) => value.toISOString()
     * }
     * ```
     */
    stringify?: Record<string, (value: any) => string>;
    /**
     * Additional path alias that will be matched to the same screen.
     */
    alias?: (string | PathConfigAlias)[];
    /**
     * Path configuration for child screens.
     */
    screens?: PathConfigMap<ParamList>;
    /**
     * Name of the initial route to use for the navigator when the path matches.
     */
    initialRouteName?: keyof ParamList;
};

type PathConfigMap

type PathConfigMap<ParamList extends {}> = {
    [RouteName in keyof ParamList]?: NonNullable<
        ParamList[RouteName]
    > extends NavigatorScreenParams<infer T extends {}>
        ? string | PathConfig<T>
        : string | Omit<PathConfig<{}>, 'screens' | 'initialRouteName'>;
};

type RouteConfig

type RouteConfig<
    ParamList extends ParamListBase,
    RouteName extends keyof ParamList,
    State extends NavigationState,
    ScreenOptions extends {},
    EventMap extends EventMapBase,
    Navigation
> = RouteConfigProps<
    ParamList,
    RouteName,
    State,
    ScreenOptions,
    EventMap,
    Navigation
> &
    RouteConfigComponent<ParamList, RouteName>;

type RouteConfigComponent

type RouteConfigComponent<
    ParamList extends ParamListBase,
    RouteName extends keyof ParamList
> =
    | {
          /**
           * React component to render for this screen.
           */
          component: ScreenComponentType<ParamList, RouteName>;
          getComponent?: never;
          children?: never;
      }
    | {
          /**
           * Lazily get a React component to render for this screen.
           */
          getComponent: () => ScreenComponentType<ParamList, RouteName>;
          component?: never;
          children?: never;
      }
    | {
          /**
           * Render callback to render content of this screen.
           */
          children: (props: {
              route: RouteProp<ParamList, RouteName>;
              navigation: any;
          }) => React.ReactNode;
          component?: never;
          getComponent?: never;
      };

type RouteConfigProps

type RouteConfigProps<
    ParamList extends ParamListBase,
    RouteName extends keyof ParamList,
    State extends NavigationState,
    ScreenOptions extends {},
    EventMap extends EventMapBase,
    Navigation
> = {
    /**
     * Optional key for this screen. This doesn't need to be unique.
     * If the key changes, existing screens with this name will be removed or reset.
     * Useful when we have some common screens and have conditional rendering.
     */
    navigationKey?: string;
    /**
     * Route name of this screen.
     */
    name: RouteName;
    /**
     * Navigator options for this screen.
     */
    options?:
        | ScreenOptions
        | ((props: {
              route: RouteProp<ParamList, RouteName>;
              navigation: Navigation;
              theme: ReactNavigation.Theme;
          }) => ScreenOptions);
    /**
     * Event listeners for this screen.
     */
    listeners?:
        | ScreenListeners<State, EventMap>
        | ((props: {
              route: RouteProp<ParamList, RouteName>;
              navigation: Navigation;
          }) => ScreenListeners<State, EventMap>);
    /**
     * Layout for this screen.
     * Useful for wrapping the screen with custom containers.
     * e.g. for styling, error boundaries, suspense, etc.
     */
    layout?: (props: {
        route: RouteProp<ParamList, RouteName>;
        navigation: Navigation;
        theme: ReactNavigation.Theme;
        children: React.ReactElement;
    }) => React.ReactElement;
    /**
     * Function to return an unique ID for this screen.
     * Receives an object with the route params.
     * For a given screen name, there will always be only one screen corresponding to an ID.
     * If `undefined` is returned, it acts same as no `getId` being specified.
     */
    getId?: ({
        params,
    }: {
        params: Readonly<ParamList[RouteName]>;
    }) => string | undefined;
    /**
     * Initial params object for the route.
     */
    initialParams?: Partial<ParamList[RouteName]>;
};

type RouteGroupConfig

type RouteGroupConfig<
    ParamList extends ParamListBase,
    ScreenOptions extends {},
    Navigation
> = {
    /**
     * Optional key for the screens in this group.
     * If the key changes, all existing screens in this group will be removed or reset.
     */
    navigationKey?: string;
    /**
     * Navigator options for this screen.
     */
    screenOptions?:
        | ScreenOptions
        | ((props: {
              route: RouteProp<ParamList, keyof ParamList>;
              navigation: Navigation;
              theme: ReactNavigation.Theme;
          }) => ScreenOptions);
    /**
     * Layout for the screens inside the group.
     * This will override the `screenLayout` of parent group or navigator.
     */
    screenLayout?:
        | ((props: {
              route: RouteProp<ParamList, keyof ParamList>;
              navigation: Navigation;
              theme: ReactNavigation.Theme;
              children: React.ReactElement;
          }) => React.ReactElement)
        | {};
    /**
     * Children React Elements to extract the route configuration from.
     * Only `Screen`, `Group` and `React.Fragment` are supported as children.
     */
    children: React.ReactNode;
};

type RouteProp

type RouteProp<
    ParamList extends ParamListBase,
    RouteName extends keyof ParamList = Keyof<ParamList>
> = Route<Extract<RouteName, string>, ParamList[RouteName]>;

type ScreenListeners

type ScreenListeners<
    State extends NavigationState,
    EventMap extends EventMapBase
> = Partial<{
    [EventName in keyof (EventMap & EventMapCore<State>)]: EventListenerCallback<
        EventMap & EventMapCore<State>,
        EventName
    >;
}>;

type StaticConfig

type StaticConfig<Bag extends NavigatorTypeBagBase> = StaticConfigInternal<
    Bag['ParamList'],
    Bag['NavigatorID'],
    Bag['State'],
    Bag['ScreenOptions'],
    Bag['EventMap'],
    Bag['NavigationList'],
    Bag['Navigator']
>;

type StaticNavigation

type StaticNavigation<NavigatorProps, GroupProps, ScreenProps> = {
    Navigator: React.ComponentType<NavigatorProps>;
    Group: React.ComponentType<GroupProps>;
    Screen: React.ComponentType<ScreenProps>;
    config: StaticConfig<NavigatorTypeBagBase>;
};

type StaticParamList

type StaticParamList<
    T extends {
        readonly config: {
            readonly screens?: Record<string, any>;
            readonly groups?: {
                [key: string]: {
                    screens: Record<string, any>;
                };
            };
        };
    }
> = FlatType<
    ParamListForScreens<T['config']['screens']> &
        ParamListForGroups<T['config']['groups']>
>;

Infer the param list from the static navigation config.

type StaticScreenProps

type StaticScreenProps<T extends Record<string, unknown> | undefined> = {
    route: {
        params: T;
    };
};

Props for a screen component which is rendered by a static navigator. Takes the route params as a generic argument.

type TypeBag

type TypeBag<
    ParamList extends ParamListBase,
    NavigatorID extends string | undefined,
    State extends NavigationState,
    ScreenOptions extends {},
    EventMap extends EventMapBase,
    NavigationList extends NavigationListBase<ParamList>,
    Navigator extends React.ComponentType<any>
> = {
    ParamList: ParamList;
    NavigatorID: NavigatorID;
    State: State;
    ScreenOptions: ScreenOptions;
    EventMap: EventMap;
    NavigationList: NavigationList;
    Navigator: Navigator;
};

type TypedNavigator

type TypedNavigator<
    Bag extends NavigatorTypeBagBase,
    Config = unknown
> = TypedNavigatorInternal<
    Bag['ParamList'],
    Bag['NavigatorID'],
    Bag['State'],
    Bag['ScreenOptions'],
    Bag['EventMap'],
    Bag['NavigationList'],
    Bag['Navigator']
> &
    (undefined extends Config
        ? {}
        : {
              config: Config;
          });

Package Files (34)

Dependencies (7)

Dev Dependencies (11)

Peer Dependencies (1)

react

Badge

To add a badge like this oneto your package's README, use the codes available below.

You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/@react-navigation/core.

Markdown

[![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/@react-navigation/core)

HTML

<a href="https://www.jsdocs.io/package/@react-navigation/core"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>

Updated 19 days ago.
Package analyzed in 6417 ms.
Missing or incorrect documentation? Open an issue for this package.

@react-navigation/core

Install

Overview

Index

Variables

Functions

Classes

Type Aliases

Variables

variable BaseNavigationContainer

Parameter

Parameter

Parameter

Parameter

Parameter

Parameter

Parameter

variable CurrentRenderContext

variable NavigationContainerRefContext

variable NavigationContext

variable NavigationHelpersContext

variable NavigationRouteContext

variable PreventRemoveContext

variable ThemeContext

Functions

function createComponentForStaticNavigation

Parameter tree

Parameter displayName

Returns

function createNavigationContainerRef

function createNavigatorFactory

Parameter Navigator

Returns

function createPathConfigForStaticNavigation

Parameter tree

Parameter options

Parameter auto

Returns

Example 1

function findFocusedRoute

function getActionFromState

function getFocusedRouteNameFromRoute

function getPathFromState

Parameter state

Parameter options

Returns

Example 1

function getStateFromPath

Parameter path

Parameter options

Example 1

function NavigationIndependentTree

function PreventRemoveProvider

function ThemeProvider

function useFocusEffect

Parameter callback

function useIsFocused

function useNavigation

Returns

function useNavigationBuilder

Parameter createRouter

Parameter options

Returns

function useNavigationContainerRef

function useNavigationIndependentTree

function useNavigationState

Parameter selector

function usePreventRemove

Parameter preventRemove

Parameter callback

function usePreventRemoveContext

function useRoute

Returns

function useStateForPath

Returns

function useTheme

function validatePathConfig

Classes

class PrivateValueStore

property ''