screenNavigation()
The navigation of a screen, for code outside React that knows the screen.
import { screenNavigation } from '@apexnative/navigation';
screenNavigation(screen) gives the navigation of a screen to code outside React that knows which screen it acts
for: a class a screen creates, a listener that gets the screen with an event, a screenProvider. It returns the same
object as useNavigation() in that screen, so its commands act from that
screen and take no ids.
Usage
A chat screen creates a session object that lives outside React. When the other side ends the call, the session closes the screen it belongs to:
import { screenNavigation } from '@apexnative/navigation';
import type { ScreenInfo } from '@apexnative/navigation';
export class ChatSession {
constructor(private readonly screen: ScreenInfo) {}
// called by your own socket when the call ends
onEnded() {
screenNavigation(this.screen).goBack();
}
}
import { useState } from 'react';
import { useScreen } from '@apexnative/navigation';
import { ChatSession } from '../chat/ChatSession';
function Chat() {
const screen = useScreen();
const [session] = useState(() => new ChatSession(screen));
// …
}
When the call ends, Chat goes back, or its modal closes, even if the user has opened another tab meanwhile. With
navigation.goBack() instead, the session would close whatever the user is looking at.
A listener gets the screen with every screen event, so it can act on that screen. Here ⌘F on an iPad keyboard opens
Search over whichever screen has the shortcut in its keyCommands:
navigation.on('keyCommandPressed', ({ screen, keyCommandId }) => {
if (keyCommandId === 'search') {
screenNavigation(screen).push('Search');
}
});
Signature
function screenNavigation(screen: ScreenInfo): ScreenNavigation
It takes the screen as { id, name } and returns a ScreenNavigation. A new object on every call: in a component,
useNavigation() keeps one for the screen.
The screen it takes
The screen is a ScreenInfo, as useScreen() returns it, and as every screen event, screenProvider and
errorFallback give it.
id
id: string
string Required.PlatformsiOSiPadOSAndroidThe id of this showing of the screen, made by the navigation: Component12. The commands go by it. A screen that has
closed keeps its id, and its commands reject: "the screen 'Component12' is gone". Don't keep a ScreenInfo past the
screen's life; drop it on screenPopped or when the screen unmounts.
name
name: string
string Required.PlatformsiOSiPadOSAndroidThe name of the screen in screens: 'Chat'. The commands don't use it; it is there for your own checks and logs.
What it returns
Every member is that of useNavigation(), acting from the screen given.
Each heading below links to its full description there.
This screen
screen
screen: ScreenInfo
ScreenInfo Required.PlatformsiOSiPadOSAndroidThe screen given, as it was passed. See useNavigation().screen.
setOptions
setOptions(options: ScreenOptionsInput<object>): void
Changes the options of the screen given, such as its title once a request ends. See useNavigation().setOptions.
The stack
push
push<Name extends ScreenName>(name: Name, ...args: ShowArgs<Name, PushConfig>): Promise<string>
Shows a screen over the screen given, in its stack; resolves with the id of the new screen. See useNavigation().push.
pop
pop(): Promise<string>
Goes back to the screen before the one given. See useNavigation().pop.
popTo
popTo(screenId: string): Promise<string>
Goes back to a screen of the stack, by its id. See useNavigation().popTo.
popToRoot
popToRoot(): Promise<string>
Goes back to the first screen of the stack of the screen given. See useNavigation().popToRoot.
replace
replace<Name extends ScreenName>(
name: Name,
...args: ShowArgs<Name, PushConfig>
): Promise<string>
Shows a screen alone in the stack of the screen given, with no back. See useNavigation().replace.
setStack
setStack<const Entries extends readonly StackEntry[]>(
...entries: CheckedEntries<Entries>
): Promise<string>
Replaces the screens of the stack of the screen given. See useNavigation().setStack.
canPop
canPop(): boolean
Whether there is a screen under the one given. Answers at once. See useNavigation().canPop.
Going back
goBack
goBack(): Promise<string>
What the back button would do on the screen given: pop(), or dismiss() of its modal or overlay. See useNavigation().goBack.
canGoBack
canGoBack(): boolean
Whether goBack() has something to do. See useNavigation().canGoBack.
dismiss
dismiss(): Promise<string>
Closes the modal or the overlay the screen given is in. See useNavigation().dismiss.
canDismiss
canDismiss(): boolean
Whether the screen given is in a modal or an overlay. See useNavigation().canDismiss.
Modals and overlays
showModal
showModal<Name extends ScreenName>(
name: Name,
...args: ShowArgs<Name, ModalConfig>
): Promise<string>
Shows a screen in a modal; the same from any screen. See useNavigation().showModal.
dismissModal
dismissModal(modalId: string): Promise<string>
Closes a modal by its id. See useNavigation().dismissModal.
dismissAllModals
dismissAllModals(): Promise<string>
Closes every modal. See useNavigation().dismissAllModals.
showOverlay
showOverlay<Name extends ScreenName>(
name: Name,
...args: ShowArgs<Name, OverlayConfig>
): Promise<string>
Shows a screen over everything. See useNavigation().showOverlay.
dismissOverlay
dismissOverlay(overlayId: string): Promise<string>
Closes an overlay by its id. See useNavigation().dismissOverlay.
dismissAllOverlays
dismissAllOverlays(): Promise<string>
Closes every overlay. See useNavigation().dismissAllOverlays.
Roots, tabs, split view, side menu
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 another root. See useNavigation().switchTo.
selectTab
selectTab(tab: number | string): Promise<void>
Selects a tab of the tabs the screen given is in. See useNavigation().selectTab.
setTabBadge
setTabBadge(badge: string | number | null, tab?: string): Promise<void>
The badge of the tab of the screen given, or of the tab with the id. See useNavigation().setTabBadge.
showInColumn
showInColumn<Name extends ScreenName>(
name: Name,
...args: ShowArgs<Name, ColumnConfig>
): Promise<string>
Shows a screen in a column of the split view the screen given is in. See useNavigation().showInColumn.
showColumn
showColumn(column: SplitColumn): Promise<void>
Shows a column of that split view. See useNavigation().showColumn.
hideColumn
hideColumn(column: SplitColumn): Promise<void>
Hides a column of that split view. See useNavigation().hideColumn.
openMenu
openMenu(side: 'left' | 'right'): Promise<void>
Opens a menu of the side menu the screen given is in. See useNavigation().openMenu.
closeMenu
closeMenu(): Promise<void>
Closes the open menu of that side menu. See useNavigation().closeMenu.
The rest of the app
setTheme
setTheme(theme: NavigationTheme): void
Changes the theme of the navigation. See useNavigation().setTheme.
setDirection
setDirection(direction: NavigationDirection): void
Changes the direction of the app. See useNavigation().setDirection.
getContext
getContext(): RegisteredContext
The app's context now. See useNavigation().getContext.
setContext
setContext(next: RegisteredContext | ((previous: RegisteredContext) => RegisteredContext)): void
Changes the app's context. See useNavigation().setContext.
getState
getState(): NavigationState
What the user sees now. See useNavigation().getState.
on
on<Name extends NavigationEventName>(
name: Name,
handler: (event: NavigationEvents[Name]) => void
): () => void
Listens to an event of the navigation; returns the function that stops. See useNavigation().on.
getPendingLink
getPendingLink(): PendingLink | null
The link that waits, or null. See useNavigation().getPendingLink.
openPendingLink
openPendingLink(): Promise<boolean>
Runs the waiting link now. See useNavigation().openPendingLink.
clearPendingLink
clearPendingLink(): void
Forgets the waiting link. See useNavigation().clearPendingLink.
Where the screen comes from
| Where | How |
|---|---|
| A component of the screen | useScreen(), or useNavigation() directly. |
| A screen event | navigation.on(…) and listeners give event.screen. |
| A button's press | onPress gets navigation of its screen already. |
screenProvider, errorFallback | Their screen prop. |
| A command | push and showModal resolve with an id; the name is the one you passed. |
A screen of an overlay or of a side menu's menu acts from elsewhere, as in a component: the overlay from the screen the user sees, the menu from its center. See The stack.
See also
useNavigation: the same object in a component.navigation: the commands for the screen the user sees.- Where the commands come from.