Repository navigation
Description
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-slonikMetadata
Metadata
Labels
Type
Projects
- StatusShow more project fieldsDone
Activity
MelvinBot commentedon Mar 13, 2026
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:
Tab switching = stack push: When a user taps a tab,
NavigationTabBardispatchesStackActions.push()(seesrc/components/Navigation/NavigationTabBar/index.tsx:96-135). ThelinkTofunction also explicitly convertsNAVIGATEactions toPUSH(src/libs/Navigation/helpers/linkTo/index.ts:156-163).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.Mitigations are insufficient:
FreezeWrapper,persistentScreens/dontDetachScreen, andusePreserveNavigatorStateare all workarounds. FreezeWrapper can only freeze screens still in the render tree (sliced-out screens are already unmounted).persistentScreensoperates 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):
RootTabNavigatorcomponent usingcreateBottomTabNavigatorwithfreezeOnBlur: trueandlazy: true— tab screens stay mounted after first render and are frozen (not unmounted) when backgroundedisSwitchingTabsWithinRootTabNavigator(), which triggers the tab navigator's internaljumpTorather than adding stack entriesRootTabNavigatorTabBar) instead of each screen rendering its ownNavigationTabBarinstanceROOT_TAB_NAVIGATOR, withgetAdaptedStateFromPathupdated to construct full tab state with all tab routes presentRootTabNavigatorParamListas their parent typeItems to address before merge (based on draft PR review):
console.log('state', state)inNavigationRoot.tsxTABS_TO_PRELOADset to empty) affects initial tab visit performance@react-navigation/bottom-tabsnative dependencyWhat 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 viausePreserveNavigatorState+ sessionStorage, preloading viausePreloadFullScreenNavigators, animation disabling for tab-like transitions, andFreezeWrapperfor 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 thisto create a draft PR,@MelvinBot <your feedback>to refine this analysis, or explain why you are rejecting Melvin's proposal.melvin-bot commentedon Mar 13, 2026
Current assignee @ZhenjaHorbach is eligible for the External assigner, not assigning anyone new.
[-]Introduce a Bottom Tab Navigator for Top-Level Navigation[/-][+][$250] Introduce a Bottom Tab Navigator for Top-Level Navigation[/+]melvin-bot commentedon Mar 13, 2026
Job added to Upwork: https://www.upwork.com/jobs/~022032516596565029852
178 remaining items
melvin-bot commentedon May 26, 2026
Current assignee @mallenexpensify is eligible for the Awaiting Payment assigner, not assigning anyone new.
mountiny commentedon May 26, 2026
We could do that, yeah
mountiny commentedon May 26, 2026
Since this was a large effort with bunch of follow ups, I would suggest $1500 bounty per the issue
ZhenjaHorbach commentedon May 26, 2026
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
luacmartins commentedon May 26, 2026
Yea, I think $1500 is fine for this one
mountiny commentedon May 26, 2026
I think that sounds fair, updating my comment
[-][$250] Introduce a Bottom Tab Navigator for Top-Level Navigation[/-][+][$1500] Introduce a Bottom Tab Navigator for Top-Level Navigation[/+]melvin-bot commentedon May 26, 2026
melvin-bot commentedon May 26, 2026
Upwork job price has been updated to $1500
mallenexpensify commentedon May 26, 2026
Payment Summary
Contributor+: @ZhenjaHorbach due $1500 via NewDot
garrettmknight commentedon May 28, 2026
$1500 approved for @ZhenjaHorbach
QichenZhu commentedon Nov 13, 2026
For the record, #85234 caused an issue where the app crashed in some edge cases, and PR #105857 has fixed it.