‹ Moving between screens

Types

Types

The types of moving between screens.

SectionMoving between screensDraftDocumented, not reviewed yet: the API can change.

ScreenNavigation

Interface

The navigation of a screen: its own commands act from it and take no ids, and the commands of the whole app are here too (switchTo, dismissAllModals, getState, on, the theme and the context), so a screen needs nothing else.

interface ScreenNavigation extends Omit<AppNavigation, keyof ScreenCommands>, ScreenCommands

Member	Type	Description
switchTo	switchTo<Name extends RootName>( name: Name, ...param: RootParam<RegisteredRoots[Name]> ): Promise<void> switchTo<const Layout extends Exclude<RootLayout, string>>( layout: Layout & NoInfer<CheckedScreens<UsesOfRoot<Layout>, RegisteredScreens>> ): Promise<void>	Replaces the whole navigation with a root of roots: the modals close, the overlays stay. Replaces the whole navigation with a root of its own, such as the screens of a deep link. A screen named alone is a root name here, so it goes as Stack('Name').
dismissModal	dismissModal(modalId: string): Promise<string>	Dismisses a modal by its id, or the modal a screen with this id is in.
dismissAllModals	dismissAllModals(): Promise<string>
dismissOverlay	dismissOverlay(overlayId: string): Promise<string>	Dismisses an overlay by its id. iOS also takes the id of a screen inside the overlay; Android takes only the overlay's own id and rejects the id of a screen inside it.
dismissAllOverlays	dismissAllOverlays(): Promise<string>
setTheme	setTheme(theme: NavigationTheme): void	Changes the theme of the navigation: the screens shown take it too, useNavigationTheme renders again.
setDirection	setDirection(direction: NavigationDirection): void	Changes the direction of the app (direction of createNavigation): the bars, the transitions and the swipe back follow at once, React content in the screens created after it. On iOS 15–16 a stack already shown keeps its direction (its bar, its swipe back and its transitions) until its next push; on iOS 17+ so does a stack that isn't on screen at the change (another tab, under a full-screen modal) when the app had no direction before.
getContext	getContext(): RegisteredContext	The app's context: context of createNavigation, as setContext changed it since.
setContext	setContext(next: RegisteredContext | ((previous: RegisteredContext) => RegisteredContext)): void	Changes the app's context: every useAppContext renders again.
getState	getState(): NavigationState	What the user sees now: the screen and the selected tab. Once a command resolves, it shows what the command did.
getPendingLink	getPendingLink(): PendingLink | null	The link that waits for when of linking, the latest one; null when none waits.
openPendingLink	openPendingLink(): Promise<boolean>	Runs the waiting link now, as in a running app, whatever its when says, and forgets it. Resolves once its route has run, with false when no link waits; a route that fails goes to onError.
clearPendingLink	clearPendingLink(): void	Forgets the waiting link.
on	on<Name extends NavigationEventName>( name: Name, handler: (event: NavigationEvents[Name]) => void ): () => void	Listens to an event of the navigation, outside the screens too; returns the function that stops listening.
screenRequired	ScreenInfo	The screen the commands act from.
push	push<Name extends ScreenName>(name: Name, ...args: ShowArgs<Name, PushConfig>): Promise<string>	Shows a screen over this one in its stack; resolves with the id of the screen shown (for a pair, the pair's id).
pop	pop(): Promise<string>	Goes back to the screen before this one in its stack. The first screen of a split view column shown over the list (a phone) goes back to the list.
popTo	popTo(screenId: string): Promise<string>	Goes back to a screen of this stack, by its id.
popToRoot	popToRoot(): Promise<string>	Goes back to the first screen of this stack.
replace	replace<Name extends ScreenName>( name: Name, ...args: ShowArgs<Name, PushConfig> ): Promise<string>	Shows a screen in place of the whole history of this stack: it comes in as a push does and is alone in the stack, so there is no back. For a point the user shouldn't go back from, such as a payment once it is made. Resolves with the id of the screen shown.
setStack	setStack<const Entries extends readonly StackEntry[]>( ...entries: CheckedEntries<Entries> ): Promise<string>	Replaces the screens of this stack: the last one shows, back goes to the one before.
showInColumn	showInColumn<Name extends ScreenName>( name: Name, ...args: ShowArgs<Name, ColumnConfig> ): Promise<string>	Shows a screen in a column of the split view this screen is in, in place of what the column shows: Details beside a list. The column comes into view: a sidebar over it goes away; collapsed into one stack (iPhone, a narrow window) the screen goes on top, and back comes here; on Android the secondary pane comes over the primary one. With a compact layout on screen and outside a split view the screen is pushed over this one.
showModal	showModal<Name extends ScreenName>( name: Name, ...args: ShowArgs<Name, ModalConfig> ): Promise<string>	Shows a screen over everything, in a stack of its own unless stack: false.
dismiss	dismiss(): Promise<string>	Closes the modal or the overlay this screen is in, with all its screens.
canPop	canPop(): boolean	There is a screen under this one in its stack, or this one is the first of a split view column shown over the list (a phone), so pop() has one to go back to. Answers at once.
canDismiss	canDismiss(): boolean	This screen is in a modal or an overlay, so dismiss() has one to close. Answers at once.
goBack	goBack(): Promise<string>	What the back button would do here: pop() when there is a screen under this one in its stack, dismiss() when it is the first screen of a modal. For a screen that opens both ways, pushed in one place and in a modal in another.
canGoBack	canGoBack(): boolean	goBack() has something to do: canPop() or canDismiss(). Answers at once.
showOverlay	showOverlay<Name extends ScreenName>( name: Name, ...args: ShowArgs<Name, OverlayConfig> ): Promise<string>	Shows a screen over everything, without taking the place of any.
showColumn	showColumn(column: SplitColumn): Promise<void>	Shows a column of the split view this screen is in, as the platform does for the split behavior: the sidebar ('primary'), the middle column ('supplementary'), the inspector. Resolves once the columns have moved. On Android the primary pane: beside the secondary one it comes back, under it the secondary pane goes away.
hideColumn	hideColumn(column: SplitColumn): Promise<void>	Hides a column of the split view this screen is in: hideColumn('primary') leaves the item alone.
openMenu	openMenu(side: 'left' | 'right'): Promise<void>	Opens a menu of the side menu this screen is in; resolves once it is open and getState() shows its screen.
closeMenu	closeMenu(): Promise<void>	Closes the menu that is open in the side menu this screen is in; resolves once it is closed and getState() shows the center.
setOptions	setOptions(options: ScreenOptionsInput<object>): void	Changes the options of this screen.
selectTab	selectTab(tab: number | string): Promise<void>	Selects a tab of the tabs this screen is in: by its index, or by the id of the tab (Tab().id()). Resolves once the state shows it, as navigation.selectTab does.
setTabBadge	setTabBadge(badge: string | number | null, tab?: string): Promise<void>	The badge of this screen's tab, or of the tab with the id; null and the number 0 take it away.

Defined in src/api/hooks/useNavigation.ts ↗

AppNavigation

Interface

interface AppNavigation

Member	Type	Description
switchTo	switchTo<Name extends RootName>( name: Name, ...param: RootParam<RegisteredRoots[Name]> ): Promise<void> switchTo<const Layout extends Exclude<RootLayout, string>>( layout: Layout & NoInfer<CheckedScreens<UsesOfRoot<Layout>, RegisteredScreens>> ): Promise<void>	Replaces the whole navigation with a root of roots: the modals close, the overlays stay. Replaces the whole navigation with a root of its own, such as the screens of a deep link. A screen named alone is a root name here, so it goes as Stack('Name').
push	push<Name extends ScreenName>(name: Name, ...args: ShowArgs<Name, PushConfig>): Promise<string>	Shows a screen in the stack of the screen the user sees; resolves with the id of the screen shown (for a pair, the pair's id).
pop	pop(): Promise<string>	Goes back in the stack of the screen the user sees; see useNavigation().pop.
popTo	popTo(screenId: string): Promise<string>	Goes back to a screen of its stack, by its id.
canPop	canPop(): boolean	pop() has a screen to go back to from the one the user sees; see useNavigation().canPop. Answers at once.
canDismiss	canDismiss(): boolean	The screen the user sees is in a modal or an overlay. Answers at once.
showColumn	showColumn(column: SplitColumn): Promise<void>	Shows a column of the split view the user is in; see useNavigation().showColumn.
hideColumn	hideColumn(column: SplitColumn): Promise<void>	Hides a column of the split view the user is in.
openMenu	openMenu(side: 'left' | 'right'): Promise<void>	Opens a menu of the side menu the user is in; resolves once it is open and getState() shows its screen.
closeMenu	closeMenu(): Promise<void>	Closes the menu that is open; resolves once it is closed and getState() shows the center, so the next command acts from there.
goBack	goBack(): Promise<string>	What the back button would do on the screen the user sees: pop(), or dismiss() of its modal.
canGoBack	canGoBack(): boolean	goBack() has something to do. Answers at once.
popToRoot	popToRoot(): Promise<string>	Goes back to the first screen of the stack of the screen the user sees.
replace	replace<Name extends ScreenName>( name: Name, ...args: ShowArgs<Name, PushConfig> ): Promise<string>	Shows a screen alone in the stack of the screen the user sees, in place of its history; see useNavigation().replace.
setStack	setStack<const Entries extends readonly StackEntry[]>( ...entries: CheckedEntries<Entries> ): Promise<string>	Replaces the screens of the stack of the screen the user sees.
showInColumn	showInColumn<Name extends ScreenName>( name: Name, ...args: ShowArgs<Name, ColumnConfig> ): Promise<string>	Shows a screen in a column of the split view of the screen the user sees; see useNavigation().showInColumn.
showModal	showModal<Name extends ScreenName>( name: Name, ...args: ShowArgs<Name, ModalConfig> ): Promise<string>	Shows a screen over everything, in a stack of its own unless stack: false.
dismissModal	dismissModal(modalId: string): Promise<string>	Dismisses a modal by its id, or the modal a screen with this id is in.
dismissAllModals	dismissAllModals(): Promise<string>
showOverlay	showOverlay<Name extends ScreenName>( name: Name, ...args: ShowArgs<Name, OverlayConfig> ): Promise<string>	Shows a screen over everything, without taking the place of any.
dismissOverlay	dismissOverlay(overlayId: string): Promise<string>	Dismisses an overlay by its id. iOS also takes the id of a screen inside the overlay; Android takes only the overlay's own id and rejects the id of a screen inside it.
dismissAllOverlays	dismissAllOverlays(): Promise<string>
selectTab	selectTab(tab: number | string): Promise<void>	Selects a tab of the tabs of the screen the user sees: by its index, or by the id of the tab. Resolves once the state shows it, so the next command acts in that tab. The state has the tab of the root's tabs only: in tabs over them (tabs in a modal) it resolves on the next change of the state, at the latest after 300 ms, and at once when the root's tabs show a tab with that index.
setTabBadge	setTabBadge(badge: string | number | null, tab?: string): Promise<void>	The badge of the tab with the id, or of the tab of the screen the user sees: a count or a short text. null and the number 0 take it away, so a count of unread messages goes as it is; the text '0' shows "0".
setTheme	setTheme(theme: NavigationTheme): void	Changes the theme of the navigation: the screens shown take it too, useNavigationTheme renders again.
setDirection	setDirection(direction: NavigationDirection): void	Changes the direction of the app (direction of createNavigation): the bars, the transitions and the swipe back follow at once, React content in the screens created after it. On iOS 15–16 a stack already shown keeps its direction (its bar, its swipe back and its transitions) until its next push; on iOS 17+ so does a stack that isn't on screen at the change (another tab, under a full-screen modal) when the app had no direction before.
getContext	getContext(): RegisteredContext	The app's context: context of createNavigation, as setContext changed it since.
setContext	setContext(next: RegisteredContext | ((previous: RegisteredContext) => RegisteredContext)): void	Changes the app's context: every useAppContext renders again.
getState	getState(): NavigationState	What the user sees now: the screen and the selected tab. Once a command resolves, it shows what the command did.
getPendingLink	getPendingLink(): PendingLink | null	The link that waits for when of linking, the latest one; null when none waits.
openPendingLink	openPendingLink(): Promise<boolean>	Runs the waiting link now, as in a running app, whatever its when says, and forgets it. Resolves once its route has run, with false when no link waits; a route that fails goes to onError.
clearPendingLink	clearPendingLink(): void	Forgets the waiting link.
on	on<Name extends NavigationEventName>( name: Name, handler: (event: NavigationEvents[Name]) => void ): () => void	Listens to an event of the navigation, outside the screens too; returns the function that stops listening.

Defined in src/api/navigation.ts ↗