Onboarding - Onboarding modal is aligned to top

[jponikarchuk]

If you haven’t already, check out our contributing guidelines for onboarding and email contributors@expensify.com to request to join our Slack channel!

---

Version Number: 9.3.41-0
Reproducible in staging?: Yes
Reproducible in production?: No
If this was caught during regression testing, add the test name, ID and link from BrowserStack: #80460
Email or phone of affected tester (no customers): jsodijsiodjnoidjsoj@gmail.com
Issue reported by: Applause Internal Team
Bug source: Exploratory - Significant User Experience Deterioration
Device used: Mac 26.2 / Chrome
App Component: Other

Action Performed:

1. Go to staging.new.expensify.com
2. Log in with new Gmail account.
3. Go through the onboarding.

Expected Result:

Onboarding modal will be centered.

Actual Result:

Onboarding modal is aligned to top.

Workaround:

Unknown

Platforms:

• Android: App
• Android: mWeb Chrome
• iOS: App
• iOS: mWeb Safari
• iOS: mWeb Chrome
• Windows: Chrome
• MacOS: Chrome / Safari

Screenshots/Videos

Video.mp4

View all open jobs on GitHub

[melvin-bot]

You have been assigned to this deploy blocker because you recently merged this PR: #80460

[melvin-bot]

💬 A slack conversation has been started in #expensify-open-source

[github-actions]

👋 Friendly reminder that deploy blockers are time-sensitive ⏱ issues! Check out the open `StagingDeployCash` deploy checklist to see the list of PRs included in this release, then work quickly to do one of the following:

1. Identify the pull request that introduced this issue and revert it.
2. Find someone who can quickly fix the issue.
3. Fix the issue yourself.

[OSBotify]

🔍 Investigation Summary

Classification: Frontend bug
Causing PR: #80460 - "fix: Color: Onboarding: The status of the progress bar relies only on the use of color" by @TaduJR (High confidence)
Related Issues: #77334 (original accessibility issue that PR #80460 was fixing)

Recommendation: REVERT

The PR makes significant accessibility improvements to the onboarding progress bar, but introduces a layout regression. Reverting is the safest approach to unblock the deploy, then the PR can be fixed and re-merged with proper testing of the layout.

Labels: No label changes recommended - this is a frontend bug affecting the App, so DeployBlockerCash should remain.

📋 Detailed Analysis

Evidence

PR #80460 was merged on 2026-03-19 at 18:06:11Z and is included in the staging deploy 9.3.41-0. The issue was reported shortly after at 21:02:06Z, and the bug is reproducible on staging but NOT on production, confirming it was introduced in this release.

Verification

The PR modifies the following key files related to onboarding layout:

• src/components/HeaderWithBackButton/index.tsx - Added accessibility attributes to progress bar
• src/styles/index.ts - Changed headerProgressBarContainer from zIndex: -1 to pointerEvents: 'none'
• All 13 onboarding pages (BaseOnboarding*.tsx files) - Updated to use dynamic progress bar positioning

The critical change is in src/styles/index.ts line 5015:

  headerProgressBarContainer: {
      position: 'absolute',
      width: '100%',
-     zIndex: -1,
+     pointerEvents: 'none',
  },

Root Cause

The progress bar container uses position: 'absolute' to center it within the header. The original zIndex: -1 placed it behind other content. PR #80460 changed this to pointerEvents: 'none' to prevent interaction while improving accessibility.

However, removing the negative z-index without properly accounting for stacking context appears to have caused the progress bar (which is absolutely positioned) to affect the layout flow of the onboarding modal container, pushing content to the top instead of allowing it to be centered.

The progress bar is absolutely positioned within the header, and without the negative z-index, it may be creating a new stacking context that interferes with the modal's vertical centering behavior.

[OSBotify]

🔍 Investigation Summary

Classification: Frontend bug
Causing PR: #80460 - "fix: Color: Onboarding: The status of the progress bar relies only on the use of color" by @TaduJR (High confidence)
Related Issues: #77334 (original accessibility issue that PR #80460 was fixing)

Recommendation: REVERT

The PR makes significant accessibility improvements to the onboarding progress bar, but introduces a layout regression. Reverting is the safest approach to unblock the deploy, then the PR can be fixed and re-merged with proper testing of the layout.

Labels: No label changes needed - DeployBlockerCash is correctly applied (Frontend bug, App deploy blocked).

📋 Detailed Analysis

Evidence

PR #80460 was merged on 2026-03-19 at 18:06:11Z and is included in the staging deploy 9.3.41-0. The issue was reported shortly after at 21:02:06Z, and the bug is reproducible on staging but NOT on production, confirming it was introduced in this release.

Melvin-bot correctly identified this PR as the likely cause, and investigation confirms it.

Verification

The PR modifies the following key files related to onboarding layout:

• src/components/HeaderWithBackButton/index.tsx - Added accessibility attributes to progress bar
• src/styles/index.ts - Changed headerProgressBarContainer from zIndex: -1 to pointerEvents: 'none'
• All 13 onboarding pages (BaseOnboarding*.tsx files) - Updated to use dynamic progress bar positioning

The critical change is in src/styles/index.ts line 5015:

  headerProgressBarContainer: {
      position: 'absolute',
      width: '100%',
-     zIndex: -1,
+     pointerEvents: 'none',
  },

Root Cause

The progress bar container uses position: 'absolute' to center it within the header. The original zIndex: -1 placed it behind other content. PR #80460 changed this to pointerEvents: 'none' to prevent interaction while improving accessibility.

However, removing the negative z-index without properly accounting for stacking context appears to have caused the progress bar (which is absolutely positioned) to affect the layout flow of the onboarding modal container, pushing content to the top instead of allowing it to be centered.

The progress bar is absolutely positioned within the header, and without the negative z-index, it may be creating a new stacking context that interferes with the modal's vertical centering behavior.

[MelvinBot]

Proposal

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

After PR #80460 merged, the onboarding modal is aligned to the top of the screen instead of being vertically centered on web (Chrome/Safari on Windows and MacOS).

What is the root cause of that problem?

PR #80460 introduced two changes that affect the onboarding modal layout:

1. zIndex: -1 replaced with pointerEvents: 'none' on headerProgressBarContainer (src/styles/index.ts:5012-5016):

 headerProgressBarContainer: {
     position: 'absolute',
     width: '100%',
-    zIndex: -1,
+    pointerEvents: 'none',
 },

This container holds the progress bar inside the header and is absolutely positioned. While pointerEvents: 'none' achieves the original intent of preventing the progress bar from intercepting taps, zIndex: -1 also created a stacking context that placed the element behind its parent's background. Removing it changes how this absolutely positioned element participates in the rendering and stacking context on web browsers, which can affect the flex layout height computation of parent containers.

2. Dynamic progressBarPercentage that can be undefined: All 13 onboarding pages changed from hardcoded progressBarPercentage values (e.g., 20, 60, 80, 100) to dynamic values from useOnboardingStepCounter(). The hook calls getOnboardingStepCounter() (src/libs/getOnboardingStepCounter.ts:106-133), which returns undefined when the current page isn't found in the computed onboarding flow. When progressBarPercentage is undefined, the if (progressBarPercentage) check in HeaderWithBackButton (src/components/HeaderWithBackButton/index.tsx:105) falls through and renders a plain Header component instead of the progress bar + flexGrow1 spacer, changing the header's internal layout structure.

The centering of the modal itself is controlled by onboardingNavigatorOuterView (flex: 1, justifyContent: 'center', alignItems: 'center') at src/styles/index.ts:1744-1748, wrapping a fixed-size inner view (640x732px on wide screens) at src/styles/index.ts:5971-5976. The most likely culprit is the zIndex: -1 removal — on web, this changes the stacking context for the absolutely positioned progress bar container, which can affect how Chrome/Safari computes the flex layout height of the containing headerBar, cascading up to affect the centering.

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

Primary fix — restore zIndex: -1 alongside pointerEvents: 'none' in src/styles/index.ts:

The headerProgressBarContainer style should keep both properties. pointerEvents: 'none' was added for a valid reason (preventing the progress bar from intercepting interactions), but zIndex: -1 is also needed to maintain the correct stacking context on web:

headerProgressBarContainer: {
    position: 'absolute',
    width: '100%',
    zIndex: -1,
    pointerEvents: 'none',
},

Secondary safeguard — provide a fallback for undefined progressBarPercentage: In each onboarding page, ensure the progressBarPercentage passed to HeaderWithBackButton is never undefined when the step counter hook returns undefined. This can be done by providing a fallback in the getOnboardingStepCounter function itself, or by using a default value at each call site (e.g., progressBarPercentage={onboardingStep?.progressBarPercentage ?? 0}).

What alternative solutions did you explore? (Optional)

• Reverting the entire PR — this would fix the centering but would lose the accessibility improvements (progress bar labels, role="progressbar", step counters). Keeping the accessibility improvements and just restoring zIndex: -1 is the targeted fix.
• Only fixing the progressBarPercentage fallback — this addresses the case where the header renders differently but may not fix the centering if the zIndex removal is the primary cause. Both changes should be applied together.

---

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.