Scroll restoration is a coordination contract between the session-history entry, the scroll owner, and layout readiness. A saved offset can be correct while restoration still fails because it is applied to the wrong entry or container, before the destination has enough scrollable extent, or again after the browser already restored it.
Checklist
- Reproduce the exact navigation shape in a real browser: link navigation,
history.back()/Back, Forward,navigate(-1), or same-document hash traversal. Record the URL, history-entry identity or router key, navigation action, scroll owner, saved offset, applied offset, and final offset after async content settles. - Decide who owns restoration. Leave
history.scrollRestorationasautowhen browser restoration is the product contract. Usemanualonly when the application or router owns the whole save-and-restore path. Competing browser and application writes can create a second jump or make success timing-dependent. - Key positions by the intended history-entry semantics. A unique location key preserves separate positions for repeated visits to the same pathname; pathname-based keys intentionally reuse a position. Do not silently switch between these contracts or collapse query/hash-distinct entries without a product reason.
- Identify the actual scroll owner.
window.scrollYdoes not represent a nestedoverflow: autoroute shell. Save and restore each intended container explicitly, and verify that a remounted container is the same logical owner before applying an old offset. - Restore only when the destination can represent the saved position. If async loaders, images, fonts, suspense boundaries, or conditional sections change the scroll extent, an immediate
scrollTo()can be clamped and look successful in logs while landing too high. Tie restoration to an observable route/data/layout readiness boundary, then confirm the offset remains stable after the content above it finishes changing. - Do not replace readiness with an arbitrary delay or an unbounded retry loop. A fixed timeout is device- and network-dependent; repeated writes fight user input and browser scroll anchoring. Bound any retry by the destination entry and stop after success, user scroll, route change, or a documented timeout.
- Treat fragments as navigation state, not just string parsing. Verify that Back/Forward between hash entries reaches the intended target after it exists. When the fragment is an accessibility navigation target, verify focus separately instead of treating correct scrolling as evidence of correct focus.
- Keep scroll anchoring enabled by default.
overflow-anchorcan reduce content-shift jumps; disable it only on the smallest demonstrated region when anchoring itself conflicts with the explicit restoration contract. - Cover new entries, not only traversals. A programmatic push or replace (a redirect,
router.replace, a guard bouncing to another route) creates a destination entry with no saved position of its own, and a router may reset it by default — for example, the Next.js Pages Routerrouter.push/router.replacescrolloption scrolls to the top and defaults totrue. A new entry that keeps a stale offset instead points to that reset being turned off, a nested scroll owner the router does not reset, or an application restore keyed to the wrong entry (item 3). Record the navigation as push/replace, not traversal, and assert the owner starts at the top or at the fragment target.
Quick probes
- Log
{ pathname, search, hash, entryKey, navigationType, owner, savedOffset, appliedOffset, finalOffset }for one Back and one Forward traversal. ReadentryKeyonly from an allowlisted router/history-state field; omit or redact every otherhistory.statevalue because it may contain unrelated application data. - At restore time, compare the saved offset with the owner's maximum possible offset (
scrollHeight - clientHeight). A smaller maximum explains a clamped write but not why the layout was unready. - Mark browser, router, and application scroll writes separately. Two writes for one entry are a stronger lead than the presence of any one listener.
- Repeat the sequence with delayed content above the saved position and with a nested scroll container. A document-only happy path is not sufficient evidence for a container restoration claim.
Boundary with sibling skills
browser-page-lifecycle-bfcache-contractsowns restoration of an existing top-levelDocument,pageshow.persisted, frozen resources, and stale state after bfcache resume. This skill owns same-document/router entry-to-position coordination.deeplink-hydrationowns reconstructing a screen from a cold URL and router parameter readiness. This skill starts after the destination history entry is known and asks where that entry should scroll.large-list-data-grid-contractsowns virtualized row measurement, prepend compensation, overscan, and anchors for rows that may not be mounted. This skill may restore the outer route or container but does not invent a virtualized-list anchor.overlay-focus-scroll-contractsowns body scroll lock, scrollbar compensation, and focus/scroll restoration when a modal or drawer closes.ssr-hydration-mismatchowns server/client DOM divergence. Async height growth without a hydration mismatch remains in this skill.
Minimal browser regression
Create route A with a meaningful saved position and content above it that resolves asynchronously, then navigate to route B and traverse Back:
- Assert the destination URL and history-entry key before checking position.
- Wait for the route's explicit data/layout-ready signal, not a sleep chosen to make the test pass.
- Assert the correct scroll owner reaches the saved offset within a small, documented tolerance.
- Collect explicit evidence that every known layout producer above or affecting the target has settled, or observe that the scroll extent remains stable across the product's final async boundary. Only after the evidence shows that no later producer remains may two animation frames serve as a final stability check. Assert there is no second jump.
- Traverse Forward and Back again to catch overwritten entry keys, duplicate listeners, and one-shot restoration.
Add a separate hash case when fragments are supported and a nested-container case when the application scrolls an element instead of the document.
PR-worthiness gate
Require a real browser traversal with the destination entry, scroll owner, saved offset, restoration timing, and final post-layout offset captured. Tie the failure to a visible wrong position, second jump, lost reading context, or broken fragment target, then add the smallest regression for that navigation shape.
The bundled Playwright fixture runs in the bundled Chromium, Firefox, and WebKit engines and exercises duplicate same-URL history entries, asynchronous layout readiness, exact saved offsets, and two-frame post-restoration stability within one Document. It does not establish branded Safari behavior, cross-document bfcache behavior, or virtualized-list anchoring.
Reject weak findings: a popstate, scrollTo, history.scrollRestoration, or overflow-anchor occurrence with no failing traversal; an offset difference within an intentional sticky-header tolerance; browser-managed restoration that remains stable after layout; a nested container that the feature does not promise to preserve; or a hypothetical async race with no clamped or late position. Do not prescribe manual, global overflow-anchor: none, arbitrary timeouts, or repeated scroll writes from source inspection alone.
Output shape
- Disposition: confirmed | candidate/needs evidence | reject | route.
- Sequence: browser, A -> B -> Back/Forward/hash/push/replace action, destination URL and entry key.
- Evidence: scroll owner, saved/applied/final offsets, maximum extent at restore time, async layout boundary, and competing writes.
- Boundary: why this is history restoration rather than bfcache, cold deep-link readiness, virtualized anchoring, or overlay scroll lock.
- Smallest fix: ownership, entry key, correct container, readiness signal, bounded cancellation, or narrowly scoped anchoring change.
- Verification: real-browser regression and any remaining timing, browser, or accessibility gap.
Sources
- MDN,
History.scrollRestorationand itsauto/manualownership modes: https://developer.mozilla.org/en-US/docs/Web/API/History/scrollRestoration - MDN,
popstate, including same-document history state and the ordering of persisted scroll state and fragment navigation: https://developer.mozilla.org/en-US/docs/Web/API/Window/popstate_event - MDN,
overflow-anchor, including default scroll anchoring and narrowly opting out when it causes a demonstrated problem: https://developer.mozilla.org/en-US/docs/Web/CSS/overflow-anchor - Playwright, browser installation and its bundled Chromium, Firefox, and WebKit builds: https://playwright.dev/docs/browsers
- Next.js Pages Router
useRouter,router.pushoptionscroll("controls scrolling to the top of the page after navigation. Defaults totrue"), whichrouter.replaceshares: https://nextjs.org/docs/pages/api-reference/functions/use-router - React Router,
ScrollRestoration,getKey, andstorageKey: https://reactrouter.com/api/components/ScrollRestoration - Public React Router issue reproducing restoration before asynchronously rendered content provides sufficient page height: https://github.com/remix-run/react-router/issues/11158
- Public React Router issue reproducing Back/navigation restoration failure with a hash router: https://github.com/remix-run/react-router/issues/11590
- Public Next.js issue showing that fragment navigation must verify target focus separately from URL/scroll behavior: https://github.com/vercel/next.js/issues/22838
- Public Next.js issue showing a host-specific iOS swipe/snapshot symptom that should not be generalized without separating page lifecycle evidence: https://github.com/vercel/next.js/issues/62133
- Public Next.js issue reproducing different Back restoration behavior across router modes: https://github.com/vercel/next.js/issues/68746