/mobile-navigation-react-navigation

name: mobile-navigation-react-navigation
description: React Navigation 7+ patterns - static and dynamic APIs, type-safe navigation, stack/tab/drawer navigators, deep linking, authentication flows, screen preloading, header customization

React Navigation Patterns

> **Quick Guide:** Use the static API for simpler TypeScript inference and automatic deep linking config. Use the dynamic API when you need runtime-dynamic screen lists. Always declare a global `RootParamList` for type-safe `useNavigation` everywhere. Use `createNativeStackNavigator` (not the JS stack) for production performance. Auth flows use conditional screen rendering via the `if` callback (static) or conditional JSX (dynamic). Deep linking config lives per-screen in the static API -- no separate config object needed.

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST declare a global `ReactNavigation.RootParamList` interface so `useNavigation` is type-safe without manual annotation)**

**(You MUST use `createNativeStackNavigator` for production apps -- the JS stack (`@react-navigation/stack`) is significantly slower and only needed for highly custom transitions)**

**(You MUST use `popTo()` to navigate back to a previous screen in the stack -- `navigate()` in v7 no longer pops back to existing screens)**

**(You MUST wrap `useFocusEffect` callbacks in `useCallback` -- without it, the effect runs on every render, not just focus changes)**

**(You MUST NOT use `navigation.navigate('NestedScreen')` to reach screens in child navigators -- v7 removed implicit nested navigation; use explicit parent targeting)**

</critical_requirements>

---

**Auto-detection:** React Navigation, @react-navigation, createNativeStackNavigator, createBottomTabNavigator, createDrawerNavigator, createStaticNavigation, NavigationContainer, useNavigation, useRoute, useFocusEffect, usePreventRemove, StaticParamList, StaticScreenProps, NativeStackNavigationProp, CompositeNavigationProp, NavigatorScreenParams, deep linking, linking config, headerSearchBarOptions, headerLargeTitle, popTo, preload

**When to use:**

• Setting up navigation structure (stack, tab, drawer) in a React Native app
• Choosing between static API and dynamic API for navigator configuration
• Adding type-safe navigation with TypeScript (param lists, typed hooks)
• Configuring deep linking (URL prefixes, path params, universal links)
• Implementing authentication flows with conditional screen rendering
• Customizing headers (large titles, search bars, custom buttons)
• Preloading screens for perceived performance
• Preventing back navigation for unsaved changes

**When NOT to use:**

• File-based routing with a managed workflow (uses its own router built on React Navigation)
• Web-only React apps (use a web router)
• Simple single-screen apps with no navigation

**Key patterns covered:**

• Static API vs dynamic API: when to use each
• Global `RootParamList` declaration for type-safe hooks everywhere
• Native stack vs JS stack performance trade-offs
• Auth flow with conditional screens (static `if` callback or dynamic JSX)
• Deep linking configuration (per-screen in static, `linking` prop in dynamic)
• Screen preloading with `navigation.preload()`
• `useFocusEffect` for screen lifecycle management
• `usePreventRemove` for unsaved changes guards
• Header customization: large titles, search bars, form sheets

**Detailed Resources:**

• [examples/core.md](examples/core.md) - Static API setup, dynamic API setup, type-safe navigation, global RootParamList
• [examples/patterns.md](examples/patterns.md) - Auth flows, deep linking, modals, tab navigator with nested stacks
• [examples/advanced.md](examples/advanced.md) - Screen preloading, state persistence, usePreventRemove, useFocusEffect, header customization
• [reference.md](reference.md) - Decision frameworks, screen options cheat sheet, v6-to-v7 migration

---

<philosophy>

Philosophy

React Navigation provides routing and navigation for React Native apps. The key decision in v7 is **static vs dynamic API**:

• **Static API** -- object-based configuration. Simpler TypeScript (types inferred from config), automatic deep linking path generation, less boilerplate. Use for most apps.
• **Dynamic API** -- component-based configuration (`<Stack.Navigator>`/`<Stack.Screen>`). Required when screen lists change at runtime or you need full programmatic control over navigator props. More verbose but more flexible.

Both APIs produce the same navigation behavior -- the difference is configuration ergonomics.

**Core principles:**

1. **Native stack by default** -- `createNativeStackNavigator` uses platform navigation primitives (UINavigationController/Fragment) for smoother transitions and lower memory. The JS stack (`@react-navigation/stack`) only when you need custom transition animations not available natively. 2. **Type safety from the root** -- Declare `ReactNavigation.RootParamList` globally so every `useNavigation()` call is type-checked without manual generics. 3. **Deep linking as first-class** -- Configure linking per-screen (static API) or in a centralized config (dynamic API). Prefixes handle custom schemes and universal links. 4. **Screen lifecycle via focus** -- Screens in a stack remain mounted when covered. Use `useFocusEffect` (not `useEffect`) for work that should pause when the screen loses focus.

**v7 behavioral changes from v6:**

• `navigate()` no longer pops back to existing screens -- use `popTo()` instead
• Implicit nested navigator navigation removed -- must target parent screen explicitly
• `headerBackTitleVisible` replaced with `headerBackButtonDisplayMode`
• Navigation state is frozen in dev mode (mutations throw)
• Theme objects now require a `fonts` property

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Static API Set