content layout shift in sidebar due to scrollbar

[johan456789]

What page of the docs did you find an issue on?

https://starlight.astro.build/getting-started/

Describe the issue

The scrollbar disappears when you collapse some sections and that causes CLS.

Screen.Recording.2026-03-09.at.23.20.49.mov

Astro doc doesn't have this problem in comparison:

Screen.Recording.2026-03-09.at.23.21.55.mov

What operating system are you using?

mac

What browser are you using?

Dia (Chromium-based)

Participation

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

[delucis]

Thanks for the issue report @johan456789!

Astro’s docs include some custom CSS which is why the issue is not visible there: https://github.com/withastro/docs/blob/273ebfb5cf36de0bbb815d65bc18a8da5386de97/src/components/starlight/Sidebar.astro#L104-L107

In theory, Starlight could use scrollbar-gutter: stable; on the scroll container to avoid this. Not sure how important or desirable it is. It would introduce an imbalanced layout when the scrollbar is not present for example:

But maybe that’s an acceptable trade-off?

[johan456789]

I think Astro's solution (always showing scrollbar) is simple and good enough. Elements moving under your cursor is not ideal.

If a cleaner look is desired, we can use scrollbar-gutter so there won't be a scrollbar shown even when it's not scrollable.

In theory, Starlight could use scrollbar-gutter: stable; on the scroll container to avoid this. Not sure how important or desirable it is. It would introduce an imbalanced layout when the scrollbar is not present for example:

There's also both-edges that can keep it centered. But since it takes up space on both sides, the padding might need to be adjusted.

Screen.Recording.2026-03-11.at.00.51.00.mov

Whichever solution you pick, I think it's best there's no CLS and it's consistent across Astro and Starlight doc.