scrollbar-gutter | CSS-Tricks

The scrollbar-gutter property provides flexibility to determine how the space the browser uses to display a scrollbar that interacts with the content on the screen. The spec describes it "reserving space for the scrollbar" and that makes sense since that's what a gutter ultimately is: a container that reserves space for whatever is in it and separates it from other elements.

So we're all on the same page, a scrollbar is that thing typically on the right side of the browser (formally referred to as the "user agent" — or UA — in the spec) that indicates your scroll position relative to the total available space on the webpage.

Those have traditionally been a visual container with a sliding indicator. These are referred to as classic scrollbars. The indicator sits inside of the gutter and the gutter takes up physical real estate on the screen when it's displayed.

Lately, though, scrollbar appearances have trended toward something much more minimal. We call those overlay scrollbars and they are either partially or fully transparent while sitting on top of the page content. In other words, unlike classic scrollbars that take up physical real estate on the screen, overlay scrollbars sit on top of the screen content.

While we're at it, a scrollbars can pop up in other places. Besides sitting flush to the right of the browser, we will see scrollbars on HTML elements where content overflows the element and the overflow property (or overflow-x and overflow-y) are set to the scroll value. And note that the existence of overflow-x means we have horizontal scrolling in addition to vertical scrolling.

That's what we're talking about. Not the indicator itself, but the container that holds it. That's the gutter. Whether a browser uses a classic or overlay scrollbar is totally up to the UA itself. That's not for us to decide. Such is true of the scrollbar width. The user agent defines that and gives us no control over it.

That's where scrollbar-gutter comes in. We can spell out whether the gutter is present in it's classic and overlay variations.

Syntax

.my-element {
  scrollbar-gutter: [ auto | [ stable | always ] && both? && force? ]
}

A double ampersand (&&) separates two or more components, all of which must occur, in any order.

A question mark (?) indicates that the preceding type, word, or group is optional (occurs zero or one times).

Values

auto (initial value): Pretty much the default behavior described so far. Setting the property to this value allows classic scrollbars to consume real estate in the UI on elements where the overflow property of those elements are set to scroll or auto. Conversely, overlay scrollbars take up no space at all by sitting on top of the element.
stable: This adds a little opinionated behavior by always reserving space for the scrollbar gutter, as long as the overflow property on the same element is set to scroll or auto and we're dealing with a classic scrollbar — even when if the box is not overflowing. Conversely, this will have no impact on an overlay scrollbar.
always: This acts the same as stable but ensures that space for the scrollbar gutter is always reserved, regardless of whether the scrollbar is classic or overlay and regardless of whether the content is overflowing or not.
both: This states that a scrollbar gutter will be placed on both sides of the element when the default gutter is displayed. You can see how this might come in handy if your design requires equal spacing on both sides of the element.
force: This is the same as applying both stable and always where the element's overflow is set to auto, scroll, visible, hidden or clip.

The Working Draft of the spec has a super handy table that breaks those definitions down into their contexts to show the relationship they have to classic and overlay scrollbars.

		Classic scrollbars		Overlay scrollbars
overflow	scrollbar-gutter	Overflowing	Not overflowing	Overflowing	Not overflowing
scroll	auto	G	G
	stable	GM	G
	always	G	G	G	G
	auto	G
	stable	G	G
	always	G	G	G	G
visible, hidden, clip	auto
	stable	f?	f?
	always	f?	f?	f?	f?

“G” represents cases where space is reserved for the scrollbar gutter, “f?” cases where space is reserved for the scrollbar gutter if force was specified, and empty cells cases where the no space is reserved.

Specification Status

The scrollbar-gutter property is defined in the Overflow Module Level 4, which is in Working Draft status. That means this is still a work in progress and could change between now and the time the draft moves to Candidate Recommendation.

the Overflow Module Level 3 specification is a Working Draft as well, so that's a good indication that (1) it will take some time for scrollbar-gutter to become a recommendation and (2) it is still very much in progress.

Browser Support

There is no browser support at the time of the last update.

Related Properties

More Information

CSS Overflow Module Level 4 Working Draft
GitHub Issue #92
The CSS Working Group At TPAC: What’s New In CSS? Including a hand-drawn proposal for the table outlining the behavior of the property values.