[$1500] Introduce a Bottom Tab Navigator for Top-Level Navigation

[mountiny]

Coming from this proposal

Background

The application consists of several tabs:
• Home
• Inbox
• Reports
• Workspaces
• Account
Each of these tabs (without home) has its own nested navigation flow implemented using stack navigators.
Some tabs contain heavy screens, particularly Inbox, Reports, and Workspaces, where complex views and large datasets are rendered.
Currently, navigation uses a root stack navigator, where each top-level tab is pushed as a screen. As a result, switching between tabs repeatedly mounts and unmounts entire navigators, because every time we navigate to a tab, we are pushing a new screen.
This introduces unnecessary overhead and makes tab switching slower than expected, especially when moving frequently between heavy screens.

Problem

When users switch between tabs, the stack-based architecture recreates navigators and screens.
This leads to:
• unnecessary mounting and unmounting
• increased navigation latency
• reduced perceived responsiveness when switching between heavy screens

Solution

Introduce a Bottom Tab Navigator inside the root stack navigator to represent the main application areas.
The root stack navigator remains, and continues to handle global flows such as:
• modals
• RHP screens
• other global navigation states
Inside the root stack we introduce a Bottom Tab Navigator that contains the main areas of the app.

Navigation structure

Root Stack Navigator
│
├─ Bottom Tab Navigator
│   ├─ Home Stack
│   ├─ Inbox Stack
|      ├─Report
│   ├─ Reports Stack
│   ├─ Workspaces Stack
|      ├─Workspace initial page
│   └─ Settings Stack
│
├─ RHP Screens
└─ Modal ScreensEach tab keeps its existing stack navigator.

Because tab navigators keep screens mounted, switching between tabs does not recreate navigators, which significantly reduces navigation work.
Additional Improvements
This approach also allows us to:
• freeze screens when they lose focus to prevent background work
• centralize the top-level tab bar in one place
• reduce navigation overhead between heavy screens
• make tab transitions more predictable and consistent

Measured Improvements
Web: ~40% faster tab switching
iOS: ~80% faster tab switching
Android: ~80% faster tab switching

Result

This aligns the navigation architecture better with how the application is structured:
• tabs represent top-level areas of the app
• tab switching becomes significantly faster
• heavy screens (Inbox, Reports, Workspaces) no longer remount unnecessarily
• background screens are frozen when blurred
• navigation UI becomes more consistent
Overall, this should significantly improve responsiveness when switching between tabs.

Here is a draft PR. Please feel free to generate an ad-hoc build and test it. Tab switching should already be working. There are still some bugs that we are currently working on, but during testing you can focus mainly on verifying the tab switching.

Upwork Automation - Do Not Edit

• Upwork Job URL: https://www.upwork.com/jobs/~022032516596565029852
• Upwork Job ID: 2032516596565029852
• Last Price Increase: 2026-05-26

Issue Owner

Current Issue Owner: @sumo-slonik

[MelvinBot]

Proposal

Please re-state the problem that we are trying to solve in this issue.

Tab switching between the five top-level areas (Home, Inbox, Reports/Search, Workspaces, Settings) is slow because every tab switch mounts and unmounts entire navigators. Users experience noticeable latency, especially when switching to heavy screens like Inbox, Reports, and Workspaces.

What is the root cause of that problem?

The app uses a custom root stack navigator (not a tab navigator) for top-level navigation. Each tab is a separate screen pushed onto this single stack via StackActions.push().

The key mechanisms that cause the overhead:

1. Tab switching = stack push: When a user taps a tab, NavigationTabBar dispatches StackActions.push() (see src/components/Navigation/NavigationTabBar/index.tsx:96-135). The linkTo function also explicitly converts NAVIGATE actions to PUSH (src/libs/Navigation/helpers/linkTo/index.ts:156-163).

2. Only the topmost 1-2 routes are rendered: useCustomRootStackNavigatorState (src/libs/Navigation/AppNavigator/createRootStackNavigator/useCustomRootStackNavigatorState/index.ts:5-18) slices the route array so only the last fullscreen route is kept in the render tree. All other previously-visited tabs are fully unmounted.

3. Mitigations are insufficient: FreezeWrapper, persistentScreens/dontDetachScreen, and usePreserveNavigatorState are all workarounds. FreezeWrapper can only freeze screens still in the render tree (sliced-out screens are already unmounted). persistentScreens operates on the already-sliced state. State preservation (usePreserveNavigatorState, sessionStorage) saves state but doesn't prevent the expensive unmount/remount cycle.

In short: the app simulates tab navigation on top of a stack navigator, causing full component lifecycle overhead on every tab switch.

What changes do you think we should make in order to solve the problem?

Introduce a Bottom Tab Navigator (@react-navigation/bottom-tabs) inside the root stack navigator to hold the main tab screens (Home, Inbox/Reports, Search, Settings, Workspaces). The root stack continues to handle modals, RHP screens, and other global flows.

Key changes (as demonstrated in draft PR Expensify/App#85234):

• New RootTabNavigator component using createBottomTabNavigator with freezeOnBlur: true and lazy: true — tab screens stay mounted after first render and are frozen (not unmounted) when backgrounded
• Tab switching uses NAVIGATE instead of PUSH — detected via isSwitchingTabsWithinRootTabNavigator(), which triggers the tab navigator's internal jumpTo rather than adding stack entries
• Centralized tab bar managed by the tab navigator (RootTabNavigatorTabBar) instead of each screen rendering its own NavigationTabBar instance
• Linking config restructured to nest all tab screen paths under ROOT_TAB_NAVIGATOR, with getAdaptedStateFromPath updated to construct full tab state with all tab routes present
• Split navigators updated to reference RootTabNavigatorParamList as their parent type

Items to address before merge (based on draft PR review):

• Remove debug console.log('state', state) in NavigationRoot.tsx
• Fix known bugs: bottom tabs visible on chat screens, iOS native padding/composer issues, broken back navigation on workspace screens
• Evaluate whether disabling preloading (TABS_TO_PRELOAD set to empty) affects initial tab visit performance
• Consider extracting a shared utility for the repeated tab state casting pattern across ~6 helper files
• Verify HybridApp compatibility with new @react-navigation/bottom-tabs native dependency

What alternative solutions did you explore? (Optional)

The current approach (stack navigator with workarounds) is effectively the alternative that's already in place. The workaround stack includes: route slicing via useCustomRootStackNavigatorState, state preservation via usePreserveNavigatorState + sessionStorage, preloading via usePreloadFullScreenNavigators, animation disabling for tab-like transitions, and FreezeWrapper for suspending non-visible screens. These mitigations add complexity without solving the fundamental problem of unnecessary mount/unmount cycles.

---

Next Steps for Contributor+ team: Reply with @MelvinBot implement this to create a draft PR, @MelvinBot <your feedback> to refine this analysis, or explain why you are rejecting Melvin's proposal.

[melvin-bot]

Current assignee @ZhenjaHorbach is eligible for the External assigner, not assigning anyone new.