Skip to main content

createStackNavigator

Define routes whose Back action retraces visited screens.

Import​

import { createStackNavigator, createStackScreen } from '@bedrock-core/navigation';

Signature​

createStackNavigator(config): StaticNavigator<'stack'>

Parameters​

ParameterTypeDefaultDescription
config*StackNavigatorConfig—Static screen map, groups and shared options
OptionTypeDefaultDescription
screensStatic screen map—Named page components, nested navigators or published destinations
groupsStatic group map—Named groups containing screens and shared options
idstringContaining route path or 'root'Stable navigator identity
initialRouteNameRoute nameFirst routeInitially selected route
screenOptionsOptions or callback{}Options shared by the stack's screens
screenListenersListener map—Listeners for server-confirmed route events

At least one route is required across screens and groups. Names must be unique within this navigator. The configuration is static; runtime conditions use a screen or group's if predicate.

Returns​

A definition passed to createStaticNavigation or nested directly in another navigator's screen map. The factory does not open a form.

Usage​

const Shop = createStackNavigator({
id: 'shop',
initialRouteName: 'Products',
screens: {
Products,
Details: createStackScreen({
screen: Details,
initialParams: { itemId: 'diamond' },
options: ({ route }) => ({ title: route.params.itemId }),
}),
},
});

createStackScreen(config) preserves the screen component's parameter type in callbacks. Shorthand Details and { screen: Details } are also accepted.

Screen configuration​

OptionTypeDefaultDescription
screen*Component, navigator, published key or reference route—Route content or destination
initialParamsPartial route parameters—Default inputs and values available during compilation
getId({ params }) => string | undefined—Match route instances by a stable identity
if() => booleanAlways availableEvaluate availability during server rendering
optionsOptions or callbackShared optionsOverride this screen's appearance
listenersListener map or callback—Observe confirmed events for this screen
navigationKeystringRoute identityContribute a static route identity
bedrock.navigation'auto' | 'server''auto'Require a server transition for this screen and its descendants

Groups accept screens, if, screenOptions and navigationKey. Unavailable routes remain visible to compilation. See nesting and availability.

Headers​

Options include title, headerShown, headerTitle, headerBackVisible, header, headerLeft and headerRight. Header renderers receive the current route, resolved options, an optional back descriptor, and a declarative backAction.

Keep header renderers pure. Use a Link with backAction for a Back control that can participate in local navigation. Runtime title changes must fit the compiled layout.

Stack operations​

The scoped navigation hook exposes push, replace, pop, popTo, popToTop and dismiss. push creates a distinct visit; pop removes history entries, while dismiss removes complete screens including their parameter-history entries.

Back can remain local within the prepared context graph. A server checkpoint retains confirmed logical history and starts another local window.