Skip to content

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

Closed
11 of 11 issues completed
Closed

Description

@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 OwnerCurrent Issue Owner: @sumo-slonik

Activity

  1. added
    BugSomething is broken. Auto assigns a BugZero manager.
    on Mar 13, 2026
  2. MelvinBot commented on Mar 13, 2026

    @MelvinBot
    Contributor

    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.

  3. added
    ExternalAdded to denote the issue can be worked on by a contributor
    on Mar 13, 2026
  4. added
    Help WantedApply this label when an issue is open to proposals by contributors
    on Mar 13, 2026
  5. melvin-bot commented on Mar 13, 2026

    @melvin-bot

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

  6. changed the title [-]Introduce a Bottom Tab Navigator for Top-Level Navigation[/-] [+][$250] Introduce a Bottom Tab Navigator for Top-Level Navigation[/+] on Mar 13, 2026
  7. melvin-bot commented on Mar 13, 2026

    @melvin-bot
  8. 178 remaining items

  9. melvin-bot commented on May 26, 2026

    @melvin-bot

    Current assignee @mallenexpensify is eligible for the Awaiting Payment assigner, not assigning anyone new.

  10. mountiny commented on May 26, 2026

    @mountiny
    ContributorAuthor

    We could do that, yeah

  11. mountiny commented on May 26, 2026

    @mountiny
    ContributorAuthor

    Since this was a large effort with bunch of follow ups, I would suggest $1500 bounty per the issue

  12. ZhenjaHorbach commented on May 26, 2026

    @ZhenjaHorbach
    Contributor

    Since this was a large effort with bunch of follow ups, I would suggest $1000 bounty per the issue

    Yeah
    It was a huge issue😅
    But besides the main PR, which took a lot of time to test and subsequent PRs, we also had a few preparatory PRs
    So I think it's fair to set $1500 here if you don't mind

  13. luacmartins commented on May 26, 2026

    @luacmartins
    Contributor

    Yea, I think $1500 is fine for this one

  14. mountiny commented on May 26, 2026

    @mountiny
    ContributorAuthor

    I think that sounds fair, updating my comment

  15. changed the title [-][$250] Introduce a Bottom Tab Navigator for Top-Level Navigation[/-] [+][$1500] Introduce a Bottom Tab Navigator for Top-Level Navigation[/+] on May 26, 2026
  16. melvin-bot commented on May 26, 2026

    @melvin-bot

    ⚠️ This issue has had its price increased by 4x or more. Please review the issue and ensure the price is correct.

  17. melvin-bot commented on May 26, 2026

    @melvin-bot

    Upwork job price has been updated to $1500

  18. mallenexpensify commented on May 26, 2026

    @mallenexpensify
    Contributor

    Payment Summary

    Contributor+: @ZhenjaHorbach due $1500 via NewDot

  19. garrettmknight commented on May 28, 2026

    @garrettmknight
    Contributor

    $1500 approved for @ZhenjaHorbach

  20. QichenZhu commented on Nov 13, 2026

    @QichenZhu
    Contributor

    For the record, #85234 caused an issue where the app crashed in some edge cases, and PR #105857 has fixed it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

Awaiting PaymentAuto-added when associated PR is deployed to productionBugSomething is broken. Auto assigns a BugZero manager.ExternalAdded to denote the issue can be worked on by a contributorWeeklyKSv2

Type

No type

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions