Virtual list scroll restoration — single authority

Definition

Scroll restoration is the UX of returning a list to the position the user was viewing after back navigation or reload. A virtual list (window virtualizer) keeps only visible rows in the DOM, so on restore, differences between estimated and measured row heights can change total document height and cause scrollY to clamp.

Single scroll authority means only one code path among bootstrap script, React effects, and virtualizer seeding decides the final scroll position. Multiple places calling scrollTo or 6-frame reassert loops at once cause flicker and jitter.

Why it matters

Infinite-scroll lists persist anchor id, scrollY, and row heights in sessionStorage to survive cold reload. But (1) if a throttled save listener re-subscribes every render, nothing gets saved; (2) if min-height placeholders are removed too early after reveal, totalSize shrinks and scrollY gets clipped; (3) bootstrap rAF×3 + inner seed + 6-frame scrollBy loops overwrite each other.

E2E that only verifies Chromium native scroll restoration yields false-green when snapshots were never saved.

How it works

1. Save: Attach passive scroll listener once ([] deps). Capture function reads latest ref. Throttle sessionStorage setItem to 250ms.
2. Bootstrap: Inline script tail calls window.scrollTo(0, y) once (remove rAF chains and load listeners).
3. React restore: Keep visibility:hidden → compare stored value to viewport offset of anchor data-row-id → one scrollBy(delta). If no anchor, fall back to pixel scrollY (no index estimation).
4. Height seed: Persist measured row heights in sessionStorage :h keys → stable getTotalSize() from first frame on reload.
5. Min-height floor: Keep placeholder after reveal; remove only when real content covers current scrollY.
6. Failsafe: Unreachable anchor + cold-fetch exhausted → reveal anyway to avoid permanent hidden blank screen.

// anti-pattern — remove N-frame reassert
for (let i = 0; i < 6; i++) {
  requestAnimationFrame(() => window.scrollBy(0, delta));
}

Practical application

• @tanstack/react-virtual measureElement after commit + one rAF is often enough for text row correction.
• E2E: reload ±16px, no jitter, deep depth drift ≤1px, sessionStorage save gate, anchorless and unreachable paths.
• history.scrollRestoration = "manual" conflicts with Next native back restore — confirm project policy.
• Split ListRestoreBootstrap into an external script file for clearer CSP and cache policy.

Trade-offs

When not to use

• Short lists with dozens of items and no virtualization (browser default restoration is enough).
• Row heights change heavily from async images while insisting on a single correction only.
• Passing E2E as "restored" without snapshot persistence.

Common mistakes

• Putting a new captureSnapshot in throttle save effect deps every render → pending timer cleared → nothing saved.
• Using only estimateSize; after deep reload totalSize drops → scrollY clamped by hundreds of px.
• Bootstrap + React + inner seed all calling scrollTo together.
• E2E verifying only native restoration and missing unsaved snapshot bugs.
• Dead helpers like reassertScrollForFrames and estimateScrollYForRowIndex left behind.

Related concepts

• list-virtualization-windowing — virtualizer and measureElement basics
• ssr-hydration-mismatch — bootstrap script vs React boundary