Hardgraph

SKILL PROCEDURE

React Navigation

Use when adding navigation to a React Native app with React Navigation — choosing between Stack, Tabs, and Drawer navigators, wiring deep linking and web URLs, typing routes, migrating from Expo Router, or diagnosing screen-mounting and header-customisation problems. Published by HardGraph, a curated graph of provenance-backed knowledge for AI agents.

react-nativenavigationroutingexpomobiledeep-linking
BEGINNER GUIDE

Understand React Navigation before using it

CATEGORY

React Navigation is catalogued under Mobile and frontend.

START HERE WHEN

Your work repeatedly involves the concepts tagged above. Open the full procedure below when the current task matches them.

Compare related skills

SKILLCATEGORYSHARED CONCEPTSEXPLANATION
React NavigationMobile and frontendCurrent skillUse when adding navigation to a React Native app with React Navigation — choosing between Stack, Tabs, and Drawer navigators, wiring deep linking and web URLs, typing routes, migrating from Expo Router, or diagnosing screen-mounting and header-customisation problems. Published by HardGraph, a curated graph of provenance-backed knowledge for AI agents.
ExpoMobile
exporeact-native
Use when building or shipping a React Native app with Expo, choosing between managed and bare workflows, adding native dependencies, configuring EAS Build or Update, or verifying Expo SDK details that drift between releases. Published by HardGraph, a curated graph of provenance-backed knowledge for AI agents.
MapboxMaps and location
navigation
Mapbox — developer platform for maps, location search, and navigation REST APIs plus GL JS and mobile SDKs. Use when adding an interactive map to web or mobile, requesting Vector/Raster Tiles or Static Images, rendering a Mapbox Style, geocoding an address or reverse-geocoding coordinates, routing turn-by-turn Directions, computing a Matrix or Isochrone, optimizing stops, map-matching GPS traces, or uploading and managing custom map data with the Uploads API and Mapbox Tiling Service.
RevenueCatPayments and subscriptions
mobile
Cross-platform subscription and in-app-purchase platform. Use when implementing paid subscriptions or one-time purchases — configuring RevenueCat products, offerings, and entitlements, integrating the Purchases SDK on iOS/Android/web/Flutter/React Native/Unity, checking entitlement status via CustomerInfo, receiving server webhooks to grant access, restoring purchases, handling StoreKit 2 and Google Play Billing, sandbox testing, or managing anonymous vs identified app user IDs — across the App Store, Play Store, Amazon, and Stripe.

React Navigation

What is HardGraph? HardGraph publishes curated, provenance-backed agent skills grounded in reproducible vendor documentation.

React Navigation is the imperative navigation library for React Native. You build a tree of navigators (Stack, Tabs, Drawer, Material Top Tabs) and navigate between screens by calling imperative methods. It is the lower-level alternative to Expo Router's file-based routing, and the two share internals but expose a different mental model.

The decision that shapes everything else

React Navigation is v7-current, and a version boundary is the single most consequential fact about a project using it. v6 and v7 differ in how navigation state is structured, how the type system is declared, and several option names — code that "worked on the last project" often targets the wrong major version. Confirm the installed major version before writing or modifying any navigator config; behaviour described from memory is a moving target.

The second early decision is native vs JS navigation. With react-native-screens enabled (the default and recommended path), screens use real native containers and unmount when off-screen. With it disabled, every screen in a stack stays mounted and rendered — fine for a prototype, a performance and state-leak problem at scale. Do not treat "screens stay mounted" as a bug when it is the documented consequence of disabling native screens.

Things that get confused

  • React Navigation vs Expo Router. Expo Router is built on top of React Navigation but is file-based and URL-first. Picking React Navigation directly is reasonable when you want explicit, imperative control or are not in an Expo project; do not assume file-based routing exists because "it's all the same library."
  • Navigators are composable, not alternatives. A Tab navigator can live inside a Stack screen; nesting is the normal way to build real apps. The mistake is reaching for one giant Stack.
  • navigate vs reset vs replace. navigate to a screen already in the stack does not remount it — it goes back to the existing instance. Use reset to wipe history (a logout flow) and replace to swap the top screen without adding to history. Confusing these is the most common "my component didn't re-render" report.
  • Params are for identification, not application state. Passing large or frequently-changing objects through params causes re-renders and history bloat. Keep params small; hold real state elsewhere.

What surprises people

Navigation state lives in React context, not in the URL. A web-style back button or shareable link only works once you configure linking — without it there is no deep linking, no web URL, and no state restoration across reloads. Linking in v7 uses a path/parse config object whose shape changed from v6; copying a v6 linking block into a v7 app is a common silent break.

What to verify rather than recall

Option names, the type-declaration API, supported navigator packages, and the linking config shape all change between major versions. Confirm them against the mirrored corpus under references/vendor/ or the live docs rather than asserting a remembered value — a stale option name fails silently (it is ignored) rather than raising an error.

References

Hardgraph / curated knowledge for agents.

STATIC EXPORT · CANONICAL SOURCE