‹ Starting the app

Types

Types

The types of starting the app.

NavigationApp

Interface

The navigation made by createNavigation, for AppRegistry.registerComponent.

interface NavigationApp<Roots extends RootsMap = RootsMap, AppScreens = Screens>

Defined in src/api/app/createNavigation.ts ↗

NavigationConfig

Type

What createNavigation takes: screens and root, or roots with initialRoot; every other key is optional.

type NavigationConfig<
  Context = void,
  Roots extends RootsMap = Record<never, never>,
  Target extends RootTarget<Roots> = RootTarget<Roots>,
  AppScreens extends Screens = Record<never, never>,
  Groups extends ScreenGroups = Record<never, never>,
  Root extends FirstRoot<Context> = FirstRoot<Context>,
  Patterns extends string = string,
> = BaseConfig<Context, AppScreens, Groups, Roots, Patterns> &
  (SingleRootConfig<Context, Root> | NamedRootsConfig<Context, Roots, Target>)

Member	Type	Description
screens	AppScreens	The screens of the app by name.
groups	{ [Group in keyof Groups]: ScreenGroup & { screens: Groups[Group] } }	Screens sharing options, by group name. Their names are in one namespace with screens: a command names a screen without its group.
presentation	Presentation	What every push, modal and overlay starts from; the settings of a command go over it.
listeners	NavigationListeners	Handlers of the events of the navigation, for as long as the app runs.
appProvider	AppProvider	Wraps the whole app once. With it every screen of screens and groups renders in one React tree inside it, so what it holds (a store, a query client, a theme) is shared and lives as long as the app does.
screenProvider	ScreenProvider	Wraps every screen on its own, inside appProvider.
errorFallback	ComponentType<ErrorFallbackProps>	What a screen that failed to render shows instead, with retry to render it again; without it the screen is empty and its top bar stays, so the user can go back. It renders inside screenProvider, unless that failed. When the start fails, it is the first screen, in place of the splash screen, and its retry runs the start again from willMount.
loadingFallback	LoadingFallback	What a screen shows while it waits for a lazy component or data (Suspense); nothing without it.
onError	(error: unknown, source: NavigationErrorSource) => void	The errors of the app: a screen that failed to render, a start that failed, and a link whose route failed. Without it they go to the console, as React and React Native report them.
options	AppOptionsInput	The default options of every screen, over the colors of the theme: options, or a chain built from the theme and the app's context ((s, { theme, context }) => …), which is built again when the theme changes.
theme	NavigationTheme	The look of the navigation: colors of the bars, tabs and backgrounds; navigation.setTheme changes it.
safeArea	{ edges: SafeAreaEdge[] }	The edges on which every screen keeps its content out of its safe area. Without it: the top and the sides, but those where the content goes under a bar (layout.safeAreaEdges); the bottom is free and a list keeps clear of it with useSafeAreaInsets(). A screen gives its own with safeArea(...) in its options.
window	WindowOptions	The app's window, behind the screens: seen around a modal as it comes in. iOSiPadOSAndroid (not supported)
direction	NavigationDirection	The direction of the app: 'rtl', 'ltr', or 'locale' for the language of the app. The bars, the transitions and the swipe back follow it, and follow navigation.setDirection at once (on iOS 15–16 a stack already shown keeps its direction until its next push; on iOS 17+ a stack not on screen at the change does when the app had no direction before). React content follows it in the screens created after a change (React Native's I18nManager, which keeps it between launches); a reload of the JavaScript mirrors the screens already open. The side menus keep their sides.
context	Context	The first value of the app's context, for every screen (useAppContext): there at once, while willMount runs too. Its type is the type of the context. navigation.setContext is the one way to change it.
willMount	() => void | PromiseLike<void>	Runs once per JavaScript runtime before the first root, while the splash screen shows. What the first root needs goes into the context with navigation.setContext.
didMount	(context: Context) => void	Runs once per JavaScript runtime, once the first root is shown, with the context.
splash	SplashConfig	The app's own splash in React Native: a component that shows after the native splash on a cold start of the app, while willMount runs; the least time it stays, whether it waits for useSplash().hide(), and how the first root replaces it. Once per process: a reload of the JavaScript goes to the first root at once.
linking	LinkingConfig<Context, Roots, Patterns, AllScreens<AppScreens, Groups>>	The links that open the app's screens: custom schemes, universal links (iOS) and App Links (Android), by path. A link runs after willMount, once the first root is shown; the link that launches the app can make that root itself (start). The app declares its schemes and domains natively (Info.plist, entitlements, AndroidManifest).
rootRequired	Root	The first root, from the context as willMount left it.
roots	never
initialRoot	never

Defined in src/api/app/createNavigation.ts ↗

Presentation

Interface

What every push, modal and overlay of the app starts from; the settings of a command go over it.

interface Presentation

Member	Type	Description
push	PushConfig
modal	Omit<ModalConfig, 'onDismiss'>
overlay	OverlayConfig

Defined in src/api/commands/presentation.ts ↗

WindowOptions

Interface

The app's window, behind every screen: seen around a modal while it comes in.

interface WindowOptions

Member	Type	Description
backgroundColor	Color	The color of the window; without it, the system background.

Defined in src/interfaces/Options.ts ↗

LinkingConfig

Interface

The links that open the app's screens: custom schemes, universal links (iOS) and App Links (Android).

interface LinkingConfig<Context = unknown, Roots extends RootsMap = RootsMap, Patterns extends string = string, AppScreens = Record<string, unknown>>

Member	Type	Description
prefixes	string[]	The starts of the URLs the app takes: 'myapp://', 'https://example.com'; what follows is the path. A URL that starts with none is not the app's. Without it every URL goes: the host of an http(s) URL is left out, and for another scheme the path starts after ://.
routesRequired	{ [Pattern in Patterns]: LinkRoute<Pattern, Context, Roots, AppScreens> }	The routes by path pattern: static parts, :param, and :param? at the end. The most specific match wins: more required parts first, then a static part before a param at the same place, then fewer parts, then the order here.
when	(context: Context) => boolean	Whether a link may run now, from the app's context: (context) => context.signedIn. While it is false the link doesn't run and waits; the latest one waiting is kept (navigation.getPendingLink). A route's own when goes over it. Without it every link runs at once. It is asked when a link comes and, for a waiting one, on each setContext: a when that reads a store (Redux, Zustand) instead isn't asked again when the store changes, so use pending: 'manual' there.
pending	'auto' | 'manual'	What a waiting link does once when lets it: 'auto' runs it when the context changes so, after the commands then on their way (setContext and switchTo of a sign-in); 'manual' keeps it for navigation.openPendingLink, which the app calls once it is ready, such as after a sign-in kept in a store. 'auto' without it.
unmatched	(url: string) => void	A URL no route takes, or with none of prefixes. Without it a warning in development.

Defined in src/api/linking/types.ts ↗

LinkRoute

Type

A route: a screen name, pushed with the params and the query as its props; a function, its open; or { start, open, when }.

type LinkRoute<Pattern extends string, Context, Roots extends RootsMap, AppScreens> =
  | NoInfer<LinkScreen<Pattern, AppScreens>>
  | LinkHandler<Pattern>
  | LinkRouteConfig<Pattern, Context, Roots>

Member	Type	Description
start	( params: LinkParams<Pattern>, link: LinkInfo ) => RootTarget<Roots> | Exclude<RootLayout, string>	The first root when the link launches the app, in place of root / initialRoot: the screen of the link with the screens to go back to, shown at once. A layout, or a root of roots (its name, or [name, param]). In a running app, a route without open shows it with navigation.switchTo.
open	LinkHandler<Pattern>	What the link does in a running app, and when it launches the app and the route has no start: then it runs once the first root is shown.
when	(context: Context) => boolean	Whether the link may run now, in place of when of linking; while it is false the link waits.

Defined in src/api/linking/types.ts ↗

LinkRouteConfig

Interface

A route with what it does when the link launches the app, when the app runs, and when it may run.

interface LinkRouteConfig<Pattern extends string, Context, Roots extends RootsMap>

Member	Type	Description
start	( params: LinkParams<Pattern>, link: LinkInfo ) => RootTarget<Roots> | Exclude<RootLayout, string>	The first root when the link launches the app, in place of root / initialRoot: the screen of the link with the screens to go back to, shown at once. A layout, or a root of roots (its name, or [name, param]). In a running app, a route without open shows it with navigation.switchTo.
open	LinkHandler<Pattern>	What the link does in a running app, and when it launches the app and the route has no start: then it runs once the first root is shown.
when	(context: Context) => boolean	Whether the link may run now, in place of when of linking; while it is false the link waits.

Defined in src/api/linking/types.ts ↗

LinkHandler

Type

What a route does in a running app: any commands.

type LinkHandler<Pattern extends string> = (
  params: LinkParams<Pattern>,
  link: LinkInfo
) => void

Defined in src/api/linking/types.ts ↗

LinkInfo

Interface

A link as a route gets it.

interface LinkInfo

Member	Type	Description
urlRequired	string	The whole URL.
pathRequired	string	The path the route matched, without the prefix and the query: user/42.
queryRequired	Record<string, string>	The query string by key; a key given twice keeps its last value.
initialRequired	boolean	Whether this link launched the app, or on Android a new activity of it.

Defined in src/api/linking/types.ts ↗

LinkParams

Type

The params of a path pattern, each a string: 'user/:userId/:tab?' gives { userId: string; tab?: string }.

type LinkParams<Pattern extends string> = Simplify<
  { [Name in RequiredParam<Segment<Pattern>>]: string } & {
    [Name in OptionalParam<Segment<Pattern>>]?: string;
  }
>

Defined in src/api/linking/types.ts ↗

PendingLink

Interface

A link that waits for when of linking.

interface PendingLink

Member	Type	Description
urlRequired	string	The whole URL.
pathRequired	string	The path, without the prefix and the query.
routeRequired	string	The pattern of its route in routes.
paramsRequired	Record<string, string>	The params of the path.
queryRequired	Record<string, string>	The query string by key.

Defined in src/api/linking/types.ts ↗

SplashConfig

Interface

The app's own splash in React Native: an animation, a progress. It shows after the native splash on a cold start of the app, once per process: not after a reload of the JavaScript, and not when Android makes a new activity while the JavaScript runs on.

interface SplashConfig

Member	Type	Description
componentRequired	ComponentType	What the splash shows: a component without props, over the whole window. It renders before willMount ends, so it is a React root of its own, outside appProvider and screenProvider, which may need what willMount prepares. The app's context is there (useAppContext), as willMount leaves it.
minDuration	number	The least time the splash stays on screen, in ms, from when it shows: the length of its animation. 0 by default.
hide	'auto' | 'manual'	When the splash leaves: 'auto' (the default) once willMount ended and minDuration passed; 'manual' waits for useSplash().hide() too.
transition	RootTransition	How the first root replaces the splash: what Root(…).transition takes, 'fade' by default. A first root with a transition of its own (Root(…).transition(…) other than 'platform') keeps it.

Defined in src/api/app/splash.ts ↗

Splash

Interface

What useSplash returns.

interface Splash

Member	Type	Description
hide	hide(): void	Lets the splash leave, with hide: 'manual': it still waits for willMount and minDuration. Does nothing once it left, or without a splash.
logoRequired	SplashLogo | undefined	The logo of the native splash, centered in the window at this size, as apex-navigation splash made it: a splash that starts from it continues the native one without a jump. Undefined without a splash made by the CLI.

Defined in src/api/app/splash.ts ↗

SplashLogo

Interface

The size of the native splash's logo: points on iOS, dp on Android.

interface SplashLogo

Member	Type	Description
widthRequired	number
heightRequired	number

Defined in src/api/app/splash.ts ↗