Preserve navigation scroll position/toggle state on page change

[duncanwerner]

What version of starlight are you using?

0.4.1

What version of astro are you using?

2.7.4

What package manager are you using?

npm

What operating system are you using?

Linux (WSL)

What browser are you using?

Chrome/Edge/Firefox

Describe the Bug

If you have a very long set of navigation links, the scroll position resets on page transitions. The same is true for toggle state, which makes the page look jumpy on transitions even without a lot of pages. It's not the end of the world but it is annoying. It would be preferable to maintain these across page changes.

This can be done using some script and it's not too heavy weight. It would be nice if this were included. Alternatively if there was a way to add custom scripts to the default layout -- something like customCss that would let me insert an Astro component or even just some TS -- I could do it myself without forking starlight.

Link to Minimal Reproducible Example

No response

Participation

• I am willing to submit a pull request for this issue.

[delucis]

Thanks for the issue. Would be nice to improve this indeed.

For a simple solution in your own project, you can add scripts using the head config option: add your JS to the public/ directory, and then add it to your site’s head in astro.config.mjs:

  head: [{ tag: 'script', attrs: { src: '/my-script.js' } }],

[duncanwerner]

Sorry, I missed that. I thought I had scoured for places to insert stuff.

I would still prefer a way to inline it (I know I can inline it in that head object, but I mean as a proper module) but this works great for the time being. If anyone is interested here's my working example (scroll position only):

(() => {

  const key = 'toc-position';
  
  let timeout = 0;

  let position = { scrollTop: 0 };

  const sidebar = document.querySelector('#starlight__sidebar > .sidebar-content');

  if (sidebar) {

    const data = sessionStorage.getItem(key);
    if (data) {
      try {
        const obj = JSON.parse(data);
        position = {
          ...position, ...obj,
        };
        sidebar.scrollTop = position.scrollTop || 0;
      }
      catch (err) {
        // ...
      }
    }

    sidebar.addEventListener('scroll', () => {
      position.scrollTop = sidebar.scrollTop;
      if (!timeout) {
        timeout = window.setTimeout(() => {
          sessionStorage.setItem(key, JSON.stringify(position));
          timeout = 0;
        }, 100);
      }
    });

  }

})();

[astridx]

I just tried this and it works great. Thank you @duncanwerner for sharing.
Now the only issue is that the open-state of the detail-elements is not saved. After clicking on a menu item, all previously closed ones open again.

This means that the scoll position is not correct in this case.

Am I missing something or is it not possible to save this state at the moment?

[duncanwerner]

Here's our current version, which saves the detail state:

https://gist.github.com/duncanwerner/d49fd9574ecd7a26d1febd0077dd012b

Example:

https://docs.treb.app

You are welcome to use it, just remember that it is fragile to future changes in Starlight.

[stereobooster]

I wonder if @swup/astro with morph config would do the trick

[Faf4a]

Wondering, any progress on this?

[doroved]

Yes, I wish scroll state saving was built into starlight

[wassfila]

I had a similar issue, and also worse, with websites having a high pages count, the menu building on each page slowed down my build time considerably. So I designed this client side shamefully injected menu with vanilla js, the advantage is the open closed state storage and the menu data are fetched only once https://github.com/MicroWebStacks/astro-big-doc/blob/main/src/layout/client_menu.js
but from Starlight I would expect more, closed state and position indeed and I was wondering if it is not possible to keep the whole menu state with ViewTransition.

[pReya]

Any reasons why the solution of @duncanwerner couldn't be merged into the project? Looks like a solid implementation to me.

[kitschpatrol]

Glad to see this being discussed, it would be great to get a fix of some sort merged in!

I tried out some modifications building on @duncanwerner's work because I ran into issues with "flash of un-scrolled content" (FOUSC?) on Safari.

https://gist.github.com/kitschpatrol/f40f3382d9b96ab23d826453aa3af1ca (see update in next comment)

Basic objectives:

• Respect the default "collapsed" state of the sidebar specified by SidebarItem config on first page navigations.
• Retain user's scroll position and expanded / collapsed sidebar sections across page navigations.
• Expand all ancestor detail elements of the active item (regardless of user's sidebar state changes).
• Ensure that the active item is visible after a page navigation (regardless of user's sidebar state changes).
• No FLOUSC ever.

Changes:

• Inline the script and use a MutationObserver to modify the sidebar ASAP.
  (The module / bundled version of Duncan's script worked great in Chrome, but I could not get it to work without occasional FLOUSC in Safari. Inlining it as-is also wasn't enough due to delayed availability of the DOM without fine-grained control over the script's placement in the main document template. So I tried an approach using a MutationObserver to take action as soon as the element is available in the DOM, which seems overkill but seems to work —  this, combined with inlining the script, solved FLOUSC on Safari, at least in my tests so far. I found that other strategies to wait for the DOM fired too late.)

• Only save to sessionStorage before going to the next page to avoid a scroll listener.

To include the script in the page, I add the SidebarStatePersistence component to an overridden Head component, which doesn't feel great... but I guess if this were to be worked further towards a PR, there's some precedent for inlining seen in other components like ThemeProvider.asto.

I also messed with creating a web component to see if I could get better control over the lifecycle to avoid FLOUSC, but didn't have any luck.

Open questions for this approach:

• What are the implications of view transitions?
• What would happen with multiple sidebars if that ends up happening.
• Since the script is inlined and not bundled / preprocessed, what's the minimum ECMAScript version that Astro targets by default?

Improvements needed:

• Avoid running the mutation observer on sidebar-less pages.
• Track the initial expand / collapse state (from SidebarItem config) on first load before sessionStorage is set, and then apply this as the default if users don't actively change expand / collapse state of sections. (For example, the page is defined with all sections collapsed, the user navigates through several sections using the "next" buttons, this would collapse sections in the sidebar behind them once they're out of that section.)

One other thing I noticed is that by default, the div#starlight__sidebar scrolls, not its div.sidebar-content child. This results in visible scroll bars tucking under the top bar, which doesn't look great. Applied this CSS to fix it, but might be something to look into if the default behavior is not the intention?

div#starlight__sidebar {
	overflow: hidden;
}

div#starlight__sidebar > div.sidebar-content {
	overflow-y: auto;
}

Anyway open to and feedback on this approach, or other proposals that would get us closer to a PR. 👍

[kitschpatrol]

Take two, simpler to inline the script right after the sidebar is added vs. keeping the script in the head and running the mutation observer.

Example of change to Sidebar.astro to add persistence:

https://gist.github.com/kitschpatrol/a517d90386c0ebc13b465c6a7ef662fa

[kitschpatrol]

I made a few more tweaks (got rid of my decadent :has query... 😅) and opened a PR.

[Faf4a]

Awesome to hear! Can't wait for this to be a native feature!

[Firgrep]

Here's my implementation if it can help anyone. I have a menu that maps a blog collection into links and when the user clicks on it, they are directed to the blog page with the menu going to the side. I wanted to preserve the scroll in the menu when the user clicks on another post. Seems to work fine with view transitions. I put this code in my root layout.

<script>
	function preserveScriptbookMenuScroll () {
        const sidebar = document.getElementById("scriptbook");
		if (!sidebar) return;

		// Get previous scroll position (set to "0" if not found)
		let scrollPositionString = sessionStorage.getItem("scrollPositionScriptbookMenu")
		if (!scrollPositionString) {
			scrollPositionString = "0";
		}
        let scrollPosition = parseInt(scrollPositionString); 

		// Set scroll position
		sidebar.scrollTop = scrollPosition;
		
		// Listen to changes in the scroll position and save it to session storage
        sidebar.addEventListener("scroll", () => {
            scrollPosition = sidebar.scrollTop;
		sessionStorage.setItem("scrollPositionScriptbookMenu", scrollPosition.toString());
        });
      }

	const recurringScripts = () => {
		preserveScriptbookMenuScroll();
	}

	document.addEventListener('astro:page-load', () => {
    	recurringScripts();
  	});
</script>

[tomwatkins1994]

Just in case anyone is still looking for a solution here that works with view transitions, I've written something that seems to work well.

The following code doesn't require storing the scroll position in session storage and also scrolls to the correct menu item when using the global search (as this selects a menu item without the user actually scrolling to it).

I've created this custom override component for the sidebar, this just uses the default component but adds a script which checks if the menu item is visible and scrolls to it if not.

Sidebar.astro

---
import type { Props } from "@astrojs/starlight/props";
import Default from "@astrojs/starlight/components/Sidebar.astro";
---

<Default {...Astro.props}><slot /></Default>

<script>
    function isElementVisibleInContainer(element: Element, container: Element) {
        const elementRect = element.getBoundingClientRect();
        const containerRect = container.getBoundingClientRect();

        return (
            elementRect.top >= containerRect.top &&
            elementRect.left >= containerRect.left &&
            elementRect.bottom <= containerRect.bottom &&
            elementRect.right <= containerRect.right
        );
    }

    // Function to persist scroll position on page change
    function setScrollPosition() {
        const sidebar = document.querySelector("#starlight__sidebar");
        const selectedMenuItem = document.querySelector(
            "#starlight__sidebar a[aria-current='page']",
        );
        if (
            sidebar &&
            selectedMenuItem &&
            !isElementVisibleInContainer(selectedMenuItem, sidebar)
        ) {
            selectedMenuItem.scrollIntoView();
        }
    }

    document.addEventListener("astro:page-load", () => {
        setScrollPosition();
    });
</script>

[stereobooster]

related #694 (comment)

[yunsii]

Astro docs https://docs.astro.build/en/getting-started/ has the same problem for now, UX is not good enough.

[apetta]

If you're using Astro v4 and View Transitions, here's a potential solution that leverages the lifecycle events of <ViewTransition /> from astro:transitions and the browser's session storage:

<script>
      document.addEventListener("astro:before-swap", () => {
        sessionStorage.setItem("scrollPosition", window.scrollY.toString());
      });

      document.addEventListener("astro:after-swap", () => {
        const scrollPosition = sessionStorage.getItem("scrollPosition");
        if (scrollPosition) {
          window.scrollTo({
            top: parseInt(scrollPosition, 10),
            behavior: "instant",
          });
          sessionStorage.removeItem("scrollPosition");
        }
      });
</script>

We're saving the current scroll position in session storage in the astro:before-swap event, and then picking it back up in the astro:after-swap event. You can add the above script and <ViewTransition /> in your layout files to preserve scroll between transitions on the pages they're used on.

[martrapp]

If you read down here you are probably still interested in further solution alternatives.
For a sidebar that

• remembers scroll state,
• state of opened/closed categories,
• will automatically open the category of the target page on navigation (if user closed it and then navigates via link in page or back navigation) and
• scrolls the current page marker into view
• provides additional support to further customize the sidebar and the current page marker

have look at the Starlight support of the Bag of Tricks: https://events-3bg.pages.dev/jotter/starlight/guide/