Customize Scroll Restoration

[fweth]

Body

Summary

A scroll restoration function similar to focus restoration, which can be called in custom swap functions but can alse be left out if someone wants to bring their own logic.

Background & Motivation

Look at this example: https://stackblitz.com/edit/withastro-astro-queig9xm?file=src%2Flayouts%2FLayout.astro

Here I don't use view transitions but normal CSS transitions, which are sometimes mightier and have better cross browser support. When you scroll down the page before clicking a link, you see that Astro immediately scrolls to top, but I'd rather have this happening inside the timeout (or another delay mechanism).

It comes from this line: https://github.com/withastro/astro/blob/1e5b72c8df709b8ab966ed1d0f74977758bbf445/packages/astro/src/transitions/router.ts#L214

Goals

• Something like swapFunctions.saveScroll().
• The user should be able to customize the scroll restoration in custom swap functions.

Example

  import { swapFunctions } from "astro:transitions/client";

  // substitutes `window.document` with `doc`
  function mySwap(doc: Document) {
    swapFunctions.deselectScripts(doc);
    swapFunctions.swapRootAttributes(doc);
    swapFunctions.swapHeadElements(doc);
    const restoreFocusFunction = swapFunctions.saveFocus();
    const restoreScrollFunction = swapFunctions.saveScroll();
		const oldMain = document.querySelector("main");
		const newMain = doc.querySelector("main");
		oldMain.style.opacity = 0;
		window.setTimeout(function() {
			oldMain.replaceWith(newMain);
			newMain.style.opacity = 0;
			newMain.clientHeight;
			newMain.style.opacity = 1;
			restoreFocusFunction();
			restoreScrollFunction();
		}, 500)
  }

[martrapp]

Hi @fweth 👋🏼, you can set the scroll position to what ever you like in a listener to the astro:after-swap event. The event fires while the renderer is still blocked and the view transition has not started yet.

This even works with the default swap function independent of custom swaps.

This technique can be used to completely avoid changes in the scroll position during navigation.

If you want, you can wait for the view transition to finish before you scroll somewhere else:

e.transition.finished.then(() => scrollTo(x, y)

[fweth]

@martrapp awesome, thanks a lot! This definitely works, but are you happy with the underlying API? It feels to me like your solution is working a bit around the API, saving the scroll position, then let Astro reset it, and then restore it manually afterwards? In my case with the exit animation, it would mean saving the scroll position, let Astro reset it, restore it, and after the visual swap, reset it again, wouldn't it be nicer if the API exposed the scroll position handling just like it exposes focus restoration, so we could call it whenever we need it?

Anyway, feel free to close the RFC if you like!

[martrapp]

Haha, good point. If we were to reinvent the client router today, it would probably look different ;-)
That might even happen someday when the Navigation API is baseline available and view transitions are standard.
For now, I am just glad the client router works out of the box for most cases and can be tweaked when needed, though not always in the most elegant way.