- Contents:
-
scrollbar-gutterwill ship on Chrome 94 in September 2021
The scrollbar-gutter CSS property (defined in CSS Overflow L4) provides control over the presence of scrollbar gutters (the space which may be reserved to display a scrollbar).
This gives Web authors more agency over how their layouts interact with the scrollbars provided by the browser, so they can e.g. prevent excessive layout changes as content expands while avoiding unwanted visuals when scrolling isn't needed.
Note that the presence of the scrollbars themselves is determined by the overflow property and the decision of whether to use classical or overlay scrollbars is up to the user agent.
The scrollbar gutter is the space between the inner border edge and the outer padding edge, where user agents may display a scrollbar.
“Classic” scrollbars are always placed in a gutter, consuming space when present, and are usually opaque.
“Overlay” scrollbars are placed over the content, not in a gutter, and are usually partially transparent. Their appearance may vary depending on whether and how the user is interacting with them.
The user agent determines whether classic scrollbars or overlay scrollbars are used. Likewise, the user agent also defines the appearance and size of scrollbars and whether they appear on the start or end edge of the box.
The syntax for the scrollbar-gutter property is:
auto | stable && both-edges?
These values have the following meaning:
auto: No changes from current behaviour. Default value.stable: When using classic scrollbars, the gutter will be present ifoverflowishidden,scrollorautoeven if the box is not overflowing. When using overlay scrollbars, the gutter will not be present.- Use case: prevent layout changes when the content grows or shrinks.
- Use case: visually align the content in a header with the content in the list next to it (as
scrollbar-gutter: stableandoverflow: hiddenwill add a gutter on a non-scrollable element).
The stable value can be used in combination with:
both-edges: If a gutter would be present on one of the inline start/end edges of the box, another must be present on the opposite edge as well.- Use case: simmetry between the spacing on both sides of the box, so the content remains centered.
- Use case: keep the layout stable regardless of the edge where the user agent decides to place the scrollbar.
The spec also includes an informative section with current attempts at extending the scrollbar-gutter property to cover more use cases: Appendix A: Possible extensions for scrollbar-gutter.
These are the contexts when space will be reserved for the scrollbar gutter:
- Using classic scrollbars:
- when
overflowisscroll - when
overflowisautoandscrollbar-gutterusesstableor (when the box is overflowing)auto
- when
overflowishiddenandscrollbar-gutterusesstable
- when
For classic scrollbars, the width of the gutter is the same as the width of the scrollbar.
This property does not influence how the scrollbars themselves are painted.
When the gutter is present but the scrollbar is not, or the scrollbar is transparent or otherwise does not fully obscure the gutter, the background of the gutter must be painted as an extension of the padding.
The scrollbar-gutter value set on the root element is propagated to the viewport. See w3c/csswg-drafts#6079 for more details (specifically this CSSWG discussion and agreements).
Effect of different values of scrollbar-gutter with classic scrollbars:
Source: scrollbar_gutter_example_01.html
Source: scrollbar_gutter_example_02.html
Before scrolling:
With scrolling:
Source: scrollbar_gutter_example_03.html