Skip to content

Navigation

@symbiote-native/navigation is SymbioteNative’s navigation library, broadly comparable in scope to react-navigation. It is built the SymbioteNative way: one shared, framework-agnostic core (packages/navigation/src/core/) drives thin React, Vue, Angular, Svelte, and Solid adapters, exactly like every other package in this monorepo.

It ships native Stack navigation built on react-native-screens’ RNSScreen/RNSScreenStack views. These give real native push/pop transitions, headers, and modals, not a JS-only fake. It also ships pure-JS Tab and Drawer navigators (bottom tabs and a swipeable side panel) for the parts of a navigation surface that don’t need a native view underneath.

Terminal window
npm install @symbiote-native/navigation

Scaffolding or extending a SymbioteNative app? npx @symbiote-native/cli new --navigation (or add --navigation in an existing app) installs and wires this for you — see @symbiote-native/cli.

The smallest possible working Stack: two screens and a push/pop button. Each screen reads its navigator handle with useStackNavigation() (or its Vue/Angular equivalent) — the narrowed handle for a Stack screen, so there’s no union and nothing to narrow by hand. See Core concepts below for the full set of hooks, composables, and injectors.

import { Stack, useStackNavigation } from '@symbiote-native/navigation/react';
function Home() {
const navigation = useStackNavigation();
return <button title="Open details" onPress={() => navigation.push('Details')} />;
}
function Details() {
const navigation = useStackNavigation();
return <button title="Go back" onPress={() => navigation.pop()} />;
}
export default function App() {
return (
<Stack initialRouteName="Home">
<Stack.Screen name="Home" component={Home} />
<Stack.Screen name="Details" component={Details} />
</Stack>
);
}
  • Stack — the native stack navigator: headers, transitions, modals.
  • Tabs — the bottom tab bar navigator.
  • Drawer — the swipeable side-panel navigator.
  • Hooks — useNavigation/useRoute/useIsFocused/useFocusEffect/useNavigationState (Svelte: the same names, as runes; Angular: their injectX equivalents; Solid: useNavigation/useRoute stay use*, but createIsFocused/createFocusEffect/createNavigationState switch to create* since each owns a subscription) across all five adapters.
  • Linking — deep linking and navigation-state persistence.
  • FAQ — frequently asked questions.

There is no navigate(). Coming from react-navigation, the single biggest point of confusion is that every navigator here exposes a small imperative handle with explicit verbs instead:

  • A Stack handle has push/pop/popToTop/popTo/replace/setParams/reset/canGoBack.
  • A Tab handle has jumpTo/setParams.
  • A Drawer handle has openDrawer/closeDrawer/toggleDrawer/jumpTo.

There is no single navigate(name) that infers push vs. tab-switch vs. drawer-open depending on context. You call the verb that matches what you mean.

Screens are registered the way each framework already registers things, not forced into one shared shape.

  • React uses JSX children (<Stack.Screen name="..." component={...} />).
  • Vue uses default-slot components (<Screen name="..." :component="..." />, or a scoped slot for Drawer’s custom content).
  • Angular uses structural marker directives on an inert ng-template (<ng-template symbioteScreen name="..." [component]="...">).
  • Svelte uses the same declarative <Screen name="..." component={...} /> marker as Vue, but discovers it differently underneath. Svelte hands a component its children as an opaque Snippet. So <Screen>/<Stack.Screen> registers itself on a context-based collector while the snippet renders, rather than being read from a children scan.
  • Solid uses the same <Stack.Screen name="..." component={...} /> JSX shape React does, but for the same reason as Svelte, not React’s. A Solid component body runs exactly once, so it can’t scan props.children any more than Svelte can. The marker registers itself on a context collector during that one render pass instead.

This is deliberate: each adapter follows its own framework’s idiom for declaring children rather than forcing one JSX-shaped convention onto Vue’s, Angular’s, Svelte’s, or Solid’s own model.

Read route/navigation with a hook. There is no props path. Every component under a navigator reads its current route and navigator handle by calling a hook (React/Vue/Solid), a rune (Svelte), or an inject function (Angular). Use useRoute()/useNavigation(), or, better, the navigator-specific useStackNavigation()/useTabNavigation()/useDrawerNavigation(). Svelte and Solid use these same names. Angular has injectRoute()/injectNavigation()/injectStackNavigation()/etc.

The navigator does not thread route/navigation into the mounted screen as a prop or @Input(). The screen’s own top-level component reads them exactly the way any component nested deeper does, so there’s nothing to forward through the layers in between. useIsFocused()/useFocusEffect()/useNavigationState() (Angular: injectIsFocused()/injectFocusEffect()/injectNavigationState()) are read the same way. See Hooks & focus for the full set.

Route params are unknown in this v1 — there is no per-navigator generic param-list type the way react-navigation’s RootStackParamList gives you. route.params always types as unknown; narrow it yourself (a type guard, a schema, a cast at the one I/O edge) on the screen that reads it.

All of the router logic lives once in core/, shared verbatim by React, Vue, Angular, Svelte, and Solid. That covers the route-stack reducer, screen-options resolution/merging, and the derivation of the native view props RNSScreen/RNSScreenStack/the header config leaves need.

Each adapter supplies only its own lifecycle glue (hooks, composables, runes, primitives, or a directive/signal pair) and the descriptor bridge that turns the core’s render output into that framework’s elements:

packages/navigation/src/
├── core/ # framework-agnostic: reducers, screen-options resolution, render-stack/-tabs/-drawer, linking-config
├── register.ts # side-effect: registers react-native-screens' native ViewConfigs
├── react/ # React lifecycle (hooks) + descriptorToReact bridge
├── vue/ # Vue lifecycle (composables) + descriptorToVue bridge
├── angular/ # Angular lifecycle (injectors/signals) + directive-based descriptor bridge
├── svelte/ # Svelte lifecycle (runes) + descriptor-subtree bridge for Tab's pure-JS bar
└── solid/ # Solid lifecycle (primitives) + descriptor-subtree bridge for Tab's pure-JS bar

A persistence bug in the route-stack reducer, or a header-layout bug in the native prop derivation, is fixed once in core/ for all five adapters — the same shared-core pattern every SymbioteNative package follows. See how it works for the general render-pipeline this sits on top of.