Skip to content

fix(pages): keep previous page visible during lazy route transitions - #792

Merged
lizhengfeng101 merged 1 commit into
alibaba:mainfrom
shaurya703:fix-nav-black-flash
Aug 8, 2026
Merged

fix(pages): keep previous page visible during lazy route transitions#792
lizhengfeng101 merged 1 commit into
alibaba:mainfrom
shaurya703:fix-nav-black-flash

Conversation

@shaurya703

Copy link
Copy Markdown
Contributor

Fixes #788

Problem

Navigating to a lazy-loaded page (/benchmark, /quickstart, /docs, /blog) re-triggered the <Suspense> fallback — a plain black <div> — so the whole page went black while the route's chunk downloaded.

Approach

Approach 3 from the issue: keep the existing fallback for the true first-load case, but prevent it from showing during in-app transitions.

  • New useTransitionedLocation() hook: returns a location that trails useLocation() by one startTransition. <Routes location={...}> renders from it, so when the next route suspends, React keeps the current page visible (transition semantics) instead of unmounting to the fallback.
  • First paint is unchanged — there is no previous content to keep, so the dark fallback still shows, preserving the intentional no-white-flash initial load.
  • ScrollToTop now keys off the displayed location, so the scroll reset happens when the new page actually appears rather than while the old page is still on screen.
  • No router migration needed — works with the existing <Routes> API on React Router 6.8.

Acceptance criteria

  • No black flash during navigation — covered by a test: navigate to a lazy route whose chunk is deliberately unresolved, assert the old page is still on screen and the fallback is absent
  • First-time load still shows the dark loading state — covered by a test rendering directly at an unresolved lazy route
  • Back/forward navigation — covered by a test using router history
  • npm test — 19/19 pass (5 files, including the new one)
  • npm run lint — 0 errors (the 2 pre-existing warnings in HeroSection.tsx/MarkdownRenderer.tsx are untouched); tsc --noEmit clean

Navigating to a lazy-loaded page (/benchmark, /quickstart, /docs, /blog)
re-triggered the Suspense fallback — a plain black div — producing a black
screen flash while the chunk downloaded.

Route changes are now applied inside a React transition via a new
useTransitionedLocation hook: <Routes> renders from a location that trails
useLocation() by one startTransition, so a suspending route keeps the
current page on screen until its chunk is ready. The black fallback still
shows on first paint, preserving the intentional dark background on
initial load. ScrollToTop now follows the displayed location, so the
scroll reset happens when the new page actually appears.

Fixes alibaba#788
@CLAassistant

CLAassistant commented Aug 8, 2026

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

@github-actions

github-actions Bot commented Aug 8, 2026

Copy link
Copy Markdown
Contributor

OpenCodeReview: Review complete: 0 finding(s) across 2 selected item(s).

@lizhengfeng101 lizhengfeng101 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@lizhengfeng101
lizhengfeng101 merged commit 3bf5ca2 into alibaba:main Aug 8, 2026
13 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

fix(pages): use startTransition to eliminate black screen flash during page navigation

3 participants