Reserve space for scrollbars in sidebar to avoid layout shift#3797
Merged
Conversation
🦋 Changeset detectedLatest commit: 9e6b674 The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
✅ Deploy Preview for astro-starlight ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
size-limit report 📦
|
ematipico
approved these changes
Mar 31, 2026
kevinzunigacuellar
approved these changes
Mar 31, 2026
delucis
added
the
✅ approved
Merged
dadezzz
pushed a commit
to dadezzz/university_notes
that referenced
this pull request
May 12, 2026
This PR contains the following updates: | Package | Change | [Age](https://docs.renovatebot.com/merge-confidence/) | [Confidence](https://docs.renovatebot.com/merge-confidence/) | |---|---|---|---| | [@astrojs/starlight](https://starlight.astro.build) ([source](https://github.com/withastro/starlight/tree/HEAD/packages/starlight)) | [`0.38.5` → `0.39.2`](https://renovatebot.com/diffs/npm/@astrojs%2fstarlight/0.38.5/0.39.2) |  |  | --- ### Release Notes <details> <summary>withastro/starlight (@​astrojs/starlight)</summary> ### [`v0.39.2`](https://github.com/withastro/starlight/blob/HEAD/packages/starlight/CHANGELOG.md#0392) [Compare Source](https://github.com/withastro/starlight/compare/@astrojs/starlight@0.39.1...@astrojs/starlight@0.39.2) ##### Patch Changes - [#​3890](withastro/starlight#3890) [`2d05e18`](withastro/starlight@2d05e18) Thanks [@​tats-u](https://github.com/tats-u)! - Fixes CSS selector for `text-autospace` styles in Chromium browsers ### [`v0.39.1`](https://github.com/withastro/starlight/blob/HEAD/packages/starlight/CHANGELOG.md#0391) [Compare Source](https://github.com/withastro/starlight/compare/@astrojs/starlight@0.39.0...@astrojs/starlight@0.39.1) ##### Patch Changes - [#​3885](withastro/starlight#3885) [`010eed1`](withastro/starlight@010eed1) Thanks [@​ArmandPhilippot](https://github.com/ArmandPhilippot)! - Fixes the version mentioned in an error message related to autogenerated sidebar groups support. - [#​3887](withastro/starlight#3887) [`b3c6990`](withastro/starlight@b3c6990) Thanks [@​delucis](https://github.com/delucis)! - Adds 13 new icons: `clock`, `desktop`, `mobile-android`, `window`, `database`, `server`, `code-branch`, `notes`, `question`, `question-circle`, `analytics`, `padlock`, and `solidjs`. ### [`v0.39.0`](https://github.com/withastro/starlight/blob/HEAD/packages/starlight/CHANGELOG.md#0390) [Compare Source](https://github.com/withastro/starlight/compare/@astrojs/starlight@0.38.5...@astrojs/starlight@0.39.0) ##### Minor Changes - [#​3618](withastro/starlight#3618) [`dcf6d09`](withastro/starlight@dcf6d09) Thanks [@​HiDeoo](https://github.com/HiDeoo)! - **⚠️ BREAKING CHANGE:** This release changes how autogenerated links work in Starlight’s sidebar configuration. If you have sidebar groups using the `autogenerate` key, you must now wrap that configuration in an `items` array: ```diff { label: 'My group', - autogenerate: { directory: 'some-dir' }, + items: [{ autogenerate: { directory: 'some-dir' } }], } ``` This change unlocks the possibility to mix autogenerated links and other links in a single group, for example: ```js { label: 'Mixed group', items: [ 'example-page', { autogenerate: { directory: 'examples' } }, { label: 'More examples', link: 'https://example.com' }, ], } ``` This release also updates the shape of autogenerated sidebar entries in route data. Autogenerated links and groups in `Astro.locals.starlightRoute.sidebar` now include an `autogenerate` object with the [configured `directory` value](https://starlight.astro.build/guides/sidebar/#autogenerated-groups): ```js { type: 'link', label: 'Example', href: '/examples/example/', isCurrent: false, autogenerate: { directory: 'examples' } } ``` - [#​3618](withastro/starlight#3618) [`dcf6d09`](withastro/starlight@dcf6d09) Thanks [@​HiDeoo](https://github.com/HiDeoo)! - **⚠️ BREAKING CHANGE:** This release changes the default collapsed state of autogenerated sidebar subgroups. Autogenerated subgroups no longer inherit the `collapsed` value from their parent group. They are now expanded by default unless explicitly configured with [`autogenerate.collapsed`](https://starlight.astro.build/reference/configuration/#collapsing-groups). If your sidebar configuration relies on a collapsed parent group to also collapse its autogenerated subgroups, update your configuration to set `autogenerate.collapsed` to `true`: ```diff { label: 'Reference', collapsed: true, items: [ - { autogenerate: { directory: 'reference' } }, + { autogenerate: { directory: 'reference', collapsed: true } }, ], } ``` - [#​3845](withastro/starlight#3845) [`4d755f5`](withastro/starlight@4d755f5) Thanks [@​delucis](https://github.com/delucis)! - Adds a `<link rel="alternate" hreflang="x-default" href="...">` tag pointing to the default locale in multilingual sites. The `x-default` alternate is used as a signal of which language to fall back to if no other is available. Learn more in Google’s [SEO localization docs](https://developers.google.com/search/docs/specialty/international/localized-versions#xdefault). - [#​3862](withastro/starlight#3862) [`ec70630`](withastro/starlight@ec70630) Thanks [@​itrew](https://github.com/itrew)! - Makes spacing of items in nested lists more consistent - [#​3872](withastro/starlight#3872) [`417a66c`](withastro/starlight@417a66c) Thanks [@​tats-u](https://github.com/tats-u)! - Enables [the CSS property `text-autospace`](https://developer.mozilla.org/docs/Web/CSS/Reference/Properties/text-autospace) in Chinese and Japanese documents. If you would prefer to disable autospacing in Chinese and Japanese pages, you can add the following custom CSS to your site: ```css [lang]:where(:lang(zh, ja)) { text-autospace: initial; } ``` - [#​3797](withastro/starlight#3797) [`9764ebd`](withastro/starlight@9764ebd) Thanks [@​delucis](https://github.com/delucis)! - Avoids the risk of layout shift when users expand and collapse sidebar groups This release can introduce additional padding to the site sidebar on certain devices to reserve space for scrollbars. You may wish to inspect your site sidebar visually when upgrading. If you would prefer to keep the previous styling, you can add the following custom CSS to your site: ```css .sidebar-pane { scrollbar-gutter: auto; } ``` - [#​3858](withastro/starlight#3858) [`6672c35`](withastro/starlight@6672c35) Thanks [@​delucis](https://github.com/delucis)! - Updates `i18next`, used for Starlight’s localization APIs, from v23 to v26 There should not be any user-facing changes from this update </details> --- ### Configuration 📅 **Schedule**: (UTC) - Branch creation - At any time (no schedule defined) - Automerge - At any time (no schedule defined) 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this PR and you won't be reminded about this update again. --- - [ ] <!-- rebase-check -->If you want to rebase/retry this PR, check this box --- This PR has been generated by [Mend Renovate](https://github.com/renovatebot/renovate). <!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiI0My4xNjAuNyIsInVwZGF0ZWRJblZlciI6IjQzLjE3MC4yMCIsInRhcmdldEJyYW5jaCI6Im1haW4iLCJsYWJlbHMiOltdfQ==-->
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
scrollbar-gutter: stableto our sidebar to ensure space is reserved for a scrollbar and avoid layout shift when sidebar groups are expanded, overflowing the viewportUser agents vary in how they render scrollbars. Some, like macOS with a trackpad, are designed to appear and disappear and overlay on top of the UI. For these devices, this PR doesn’t change anything:
However, in other circumstances, scrollbars require a gutter which is deducted from an element’s width (with padding etc. applied from the gutter’s edge). In these cases, the change in this PR reserves that gutter space even for sidebars that do not overflow the viewport:
Note the additional whitespace between the group carets and the sidebar border in the “after” screenshot.
This isn’t an amazing change to have to make: for sites whose scrollbar never overflows, user agents that need it will still reserve that extra space, unbalancing the layout pointlessly. Having the even padding on both sides of the scrollbar would be visually more pleasing, I think.
There is also the
scrollbar-gutter: stable both-edgesvariant, which while balancing spacing either side of the scrollbar content, would introduce a lot of extra whitespace on the outer edge. You would think you might be able to adjust for that with padding but a) we don’t know when a gutter is reserved and when not and b) we don’t know the gutter width to know how much to reduce padding by.So it’s a choice between prettier layout and avoiding layout shift when users interact. On balance, it’s probably worth avoiding layout shift and there are design solutions we could explore to lessen the visual impact (such as removing the border for example).