Skip to main content

useNavigation

Read and operate the static navigation tree from a screen component.

Import​

import { useNavigation } from '@bedrock-core/navigation';

Signature​

useNavigation(): NavigationProp
useNavigation(screenName): RegisteredNavigation

Parameters​

ParameterTypeDefaultDescription
screenNameRegistered screen nameRoot scopeSelect the navigator containing this screen

A named scope resolves the nearest containing navigator. An unqualified call uses the registered root. Nested names must be unambiguous or belong to the containing branch.

Returns​

MemberDescription
navigate(name, params?, options?)Update the focused matching route or visit another route
goBack(), canGoBack()Retrace logical history, bubble to a parent, then apply the root Back policy
getState(), isFocused(), getId(), getParent(id?)Read confirmed state and containing navigators
reset(state), dispatch(action)Replace state or dispatch a portable navigation action
setParams(), replaceParams(), pushParams()Merge, replace or add parameter history
setOptions()Change values such as titles without changing compiled geometry
addListener(), removeListener()Subscribe to server-confirmed events

Stack scopes also expose push, replace, pop, popTo, popToTop and dismiss. Tab scopes expose jumpTo. CommonActions, StackActions and TabActions create corresponding action objects.

Usage​

function SaveButton() {
const navigation = useNavigation();
return <Button onPress={() => {
saveSelection();
navigation.navigate('Done');
}}><Text>{'Save'}</Text></Button>;
}

An ordinary server button inside the navigator automatically confirms the actual local route and history before its callback runs. A callback can therefore call getState() or navigate from that confirmed position.

Use Link or useLinkProps() for declarative client navigation. Calling a hook method from an onPress callback runs on the server.

useRoute() reads the current page's parameters. useNavigationState() selects data from confirmed state. Native toggles do not rerun components; reserve live text dimensions for values that can change.

useIsFocused(), useFocusEffect() and usePreventRemove() require explicit server navigation on the screen, a containing screen, or the root.

Events​

Configured listeners support focus, blur, state and preventable beforeRemove; top tabs also expose preventable tabPress. Preventable listeners require server navigation. Local visits do not replay intermediate focus events. Native form cancellation dismisses the host.

addListener() returns an idempotent disposer. A listener can also be removed with removeListener(event, listener).

External access​

createNavigationContainerRef() gives commands and services a typed handle to a mounted root, addressed explicitly through forPlayer(player).