feat:migrate to standard navigation shared adapter by oleksandrzavarzin-callstack · Pull Request #581 · callstack/react-native-bottom-tabs

oleksandrzavarzin-callstack · 2026-09-11T10:01:56Z

What

Expo SDK 56 dropped Expo Router's dependency on @react-navigation/* in favour of a vendored fork. @bottom-tabs/react-navigation imports the real thing, so on SDK 56+ two copies of React Navigation load and their contexts stop lining up.

This moves the tab view into a new framework-agnostic package, @bottom-tabs/standard-navigation, built on the standard-navigation contract. One implementation, two adapters:

Expo SDK	Package	Integration
56+	`@bottom-tabs/standard-navigation`	`unstable_createStandardRouterNavigator`
52 to 55	`@bottom-tabs/react-navigation`	`withLayoutContext`

@bottom-tabs/react-navigation's public API is unchanged - same exports, same types, same theme-derived tint defaults. It becomes a thin adapter over the shared view.

Notable

Dropped the color dependency for React Native's processColor. color is ESM-only, so every consumer who writes tests had to patch transformIgnorePatterns before Jest would run at all.
The peer on @react-navigation/native stays at >=7. An earlier revision raised it to >=7.3.0, which broke npm install outright for SDK 52-55 apps locked below that - and nothing on that path needs 7.3.
NativeBottomTabsContent carries its event map and navigator props on phantom type-only properties. Without them an integrator loses every navigator prop at the call site: tabBarActiveTintColor and friends become type errors.
unstable_createStandardRouterNavigator is marked unstable by Expo and may change between minors. We deliberately don't call it ourselves, so a break stays in app code.
On the Expo Router path a custom tabBar receives { state, descriptors, actions, emitter } rather than a navigation object, so @react-navigation/bottom-tabs' BottomTabBar can't be used there. The React Navigation path is unaffected.

How to test

yarn && yarn build
yarn test        # 96 tests across 5 workspaces
yarn lint && yarn typecheck

apps/expo-router-test runs one assertion suite against both adapters under a real Expo Router tree, with a console spy that fails on any warning or error.

Verified on an app scaffolded from create-expo-app --template default@sdk-57 (Expo 57, React Native 0.86.3, React 19.2.3):

iOS 26 and Android 17 - builds and bundles, Liquid Glass and Material 3 tab bars render with tint and badge, tapping routes between screens. No JS warnings or errors.
@react-navigation/* is absent from node_modules entirely, so there's no second copy to line up - everything resolves through Expo Router's vendored fork.

The SDK 52-55 path was checked separately: the documented withLayoutContext recipe typechecks clean against a real expo-router@55 install, at both 7.1.33 and 7.3.0.

Screenshots

iOS 26	Android 17

thiagobrez · 2026-09-15T08:08:46Z

@@ -0,0 +1,12 @@
+---
+'@bottom-tabs/navigation': minor


Let's call this new package @bottom-tabs/standard-navigation to keep consistency with React Navigation

thiagobrez · 2026-09-15T08:10:14Z

+`NativeBottomTabsContent` carries its event map and navigator props on phantom properties, so an integrator can type `tabBarActiveTintColor`, `tabBar` and the rest. Neither is inferable from the contract on its own - the event map appears only as an argument to `emitter.emit`, and the navigator props only inside an `Omit<…>`.
+
+`createNativeBottomTabNavigator` renders through the shared navigator, and keeps building its own state with `useNavigationBuilder`, so `state.key` and the per-route `navigation` and `route` objects a custom `tabBar` reads stay intact.
+
+`@bottom-tabs/react-navigation` now requires `@react-navigation/native` 7.3.0 or newer, which is the version that introduced `createStandardNavigationFactories` used by the documented shared-navigator recipe


All of this is unnecessary for the changeset

Match the naming of @bottom-tabs/react-navigation, and trim the changeset down to the release-note facts. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

thiagobrez · 2026-09-15T15:26:32Z

 <PackageManagerTabs command="install react-native-bottom-tabs" />

-If you are going to use [React Navigation / Expo Router Integration](/docs/guides/usage-with-react-navigation) make sure to install `@bottom-tabs/react-navigation`.
+If you are going to use the [React Navigation integration](/docs/guides/usage-with-react-navigation), also install `@bottom-tabs/react-navigation`.


Shouldn't it be here React Navigation or Expo SDK < 56? Or I'm missing something?

Yep, that's true.
I've added "Expo SDK 55+" note to it.

thiagobrez · 2026-09-15T15:29:03Z

@@ -0,0 +1,116 @@
+import { NavigationContainer } from '@react-navigation/native';


Not related to this file specifically, but the example app should be named example-expo-router to follow the convention of the other example apps

It's a test harness rather than the example Expo router app (for that option, we will have expo-template, after it's updated). It just checks whether our two adapters, driven by a real Expo Router and a real React Navigation, pass the same correct props to the tab view.

thiagobrez · 2026-09-21T16:17:34Z

+
+### Custom tab bar
+
+The `tabBar` function receives `state`, `descriptors`, `actions` and `emitter` - the vocabulary of the navigation contract rather than a React Navigation `navigation` object. If your tab bar needs the router, call `useNavigation()` from `expo-router` inside it.


Remove AI text

Suggested change

The `tabBar` function receives `state`, `descriptors`, `actions` and `emitter` - the vocabulary of the navigation contract rather than a React Navigation `navigation` object. If your tab bar needs the router, call `useNavigation()` from `expo-router` inside it.

The `tabBar` function receives `state`, `descriptors`, `actions` and `emitter`. If your tab bar needs the router, call `useNavigation()` from `expo-router` inside it.

thiagobrez · 2026-09-21T16:18:19Z

+
+The `tabBar` function receives `state`, `descriptors`, `actions` and `emitter` - the vocabulary of the navigation contract rather than a React Navigation `navigation` object. If your tab bar needs the router, call `useNavigation()` from `expo-router` inside it.
+
+`BottomTabBar` from `@react-navigation/bottom-tabs` cannot be used here, since it expects a React Navigation `navigation` object.


oleksandrzavarzin-callstack added 11 commits September 10, 2026 15:35

test(react-navigation): cover the current navigator behaviour

ee9006d

feat(navigation): add @bottom-tabs/navigation

eff21b1

feat(react-navigation): delegate to @bottom-tabs/navigation

14e3e17

test(expo-router-test): add an expo-router integration harness

978f887

docs: document the standard-navigation entry for Expo Router

2b2268c

refactor(react-navigation): drop the color dependency

56c2c7f

fix(react-navigation): keep the full tab bar contract

3dcd9e3

docs: correct the Expo Router warning and list the new package

67f3332

fix(react-navigation): record the peer bump in the lockfile

dbc0727

fix(navigation): let integrators infer the navigator props

b46c8bf

docs: type the shared navigator recipe

33363a5

oleksandrzavarzin-callstack marked this pull request as ready for review September 11, 2026 14:20

thiagobrez reviewed Sep 15, 2026

View reviewed changes

oleksandrzavarzin-callstack and others added 2 commits September 15, 2026 11:09

refactor: rename the shared package to @bottom-tabs/standard-navigation

ec37666

Match the naming of @bottom-tabs/react-navigation, and trim the changeset down to the release-note facts. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

fix: skip packages without a manifest when building the babel aliases

5d71839

thiagobrez reviewed Sep 15, 2026

View reviewed changes

Comment thread docs/docs/docs/guides/usage-with-expo-router.mdx

oleksandrzavarzin-callstack added 2 commits September 16, 2026 10:20

docs: add quick-start for Expo≤55

2cc28f1

fix(react-navigation): restore the >=7 peer on @react-navigation/native

a65309c

thiagobrez reviewed Sep 21, 2026

View reviewed changes

Navigation Menu

feat:migrate to standard navigation shared adapter - #581

feat:migrate to standard navigation shared adapter#581
oleksandrzavarzin-callstack wants to merge 15 commits into
callstack:mainfrom
oleksandrzavarzin-callstack:feat/migrate-to-standard-navigation-shared-adapter

oleksandrzavarzin-callstack commented Sep 11, 2026 •

edited

Loading

Uh oh!

thiagobrez Sep 15, 2026

Uh oh!

thiagobrez Sep 15, 2026

Uh oh!

thiagobrez Sep 15, 2026

Uh oh!

oleksandrzavarzin-callstack Sep 16, 2026

Uh oh!

thiagobrez Sep 15, 2026

Uh oh!

oleksandrzavarzin-callstack Sep 16, 2026

Uh oh!

Uh oh!

thiagobrez Sep 21, 2026

Uh oh!

thiagobrez Sep 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		@@ -0,0 +1,116 @@
		import { NavigationContainer } from '@react-navigation/native';


		### Custom tab bar

		The `tabBar` function receives `state`, `descriptors`, `actions` and `emitter` - the vocabulary of the navigation contract rather than a React Navigation `navigation` object. If your tab bar needs the router, call `useNavigation()` from `expo-router` inside it.


		The `tabBar` function receives `state`, `descriptors`, `actions` and `emitter` - the vocabulary of the navigation contract rather than a React Navigation `navigation` object. If your tab bar needs the router, call `useNavigation()` from `expo-router` inside it.

		`BottomTabBar` from `@react-navigation/bottom-tabs` cannot be used here, since it expects a React Navigation `navigation` object.

Conversation

oleksandrzavarzin-callstack commented Sep 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Notable

How to test

Screenshots

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

oleksandrzavarzin-callstack commented Sep 11, 2026 •

edited

Loading