The CSS scroll-state() query lets styles respond to a container's scroll behavior instead of requiring JavaScript. Revealing navigation on scroll-up and animating a back-to-top link are two common cases it covers.

What kind of query it is

Despite the function-like parentheses, scroll-state() is not a function. It is a container query (@container), in the same family as style(). The query asks whether a particular feature of a container holds a specific value. When that feature is present and matches, the styles inside the brackets apply. When the feature is missing or holds a different value, the query is false and those styles are ignored.

Syntax

@container scroll-state( <scroll-state-feature>: <value> ) {
  /* styles */
}

The four features

scroll-state() exposes four features, each with its own set of accepted values.

scrolled

Tests whether a container has been scrolled in a given direction.

  • none: no relative scroll has occurred on the container.
  • top, right, bottom, left: the most recent relative scroll moved toward that edge.
  • block-start, inline-start, block-end, inline-end: the most recent relative scroll moved toward that edge, resolved through writing-mode.
  • x: the most recent relative scroll was horizontal; y: vertical.
  • block: the most recent relative scroll was in either block direction; inline: either inline direction, again resolved through writing-mode.

scrollable

Tests whether a container can be scrolled in a given direction.

  • none: the container has no scrollable overflow.
  • top, right, bottom, left: scrollable overflow exists past that edge.
  • block-start, inline-start, block-end, inline-end: scrollable overflow past that edge, resolved through writing-mode.
  • x: horizontal scrollable overflow; y: vertical scrollable overflow.
  • block: scrollable overflow in the block direction; inline: in the inline direction, resolved through writing-mode.

stuck

Tests whether a sticky-positioned element is stuck.

  • none: the element has not moved in any direction — also its starting state.
  • top, right, bottom, left: the element has moved and is stuck to that edge.
  • block-start, inline-start, block-end, inline-end: the element is stuck to that edge, resolved through writing-mode.

snapped

Tests whether a snap target has been snapped on a given axis.

  • none: the element is not a snap target.
  • x: horizontal snap target; y: vertical snap target.
  • block: snap target in the block direction; inline: in the inline direction, resolved through writing-mode.
  • both: snap target in both directions.

A back-to-top link can slide into view with the scrolled feature. Once the scroll container is scrolled toward block-end (downward here), a translate applies and the .toplink element animates into the visible area. Because the change is a transition, scrolling back the other way animates it out again; in this demo only block-start and block-end are possible directions.

.toplink {
  position: fixed;
  bottom: 0.125em;
  right: 1em;
  translate: 0 200px;
  transition: translate 0.5s;  @container top-revealer scroll-state(scrolled: block-end) {
    translate: 0 0;
    transition: translate 0.5s;
  }
}

Indicating direction with scrollable

A directional cue matters when scroll direction is not self-evident — a translated page or a hero image filling the viewport can obscure it. An arrow animating toward the correct edge is one option. Note that scrollable switches off at the end of the scrollable area: at the block-end of the page (the bottom, in this case), scrollable: block-end is no longer true and the indicator reverts to its default, here display: none.

.scrollindicator {
  display: none;  @container top-revealer scroll-state(scrollable: block-end) {
      display: block;
  }
}

Pairing scrollable with scrolled lets you hide the indicator once the container has been scrolled in either the block-start or block-end direction. Both are needed: while positioned mid-page and scrolling up, scrolled: block-end stops being true and the indicator would otherwise reappear.

.scroll-indicator {
  display: none;  @container top-revealer scroll-state(scrollable: block-end) {
    display: block;
  }
  
  @container top-revealer scroll-state(scrolled: block-end) or scroll-state(scrolled: block-start) {
    display: none;
  }
}

stuck and the wrapper requirement

Navigation that sticks at the top can change its appearance once stuck. Unlike the cases above, stuck is evaluated on the element that gets stuck, not on the scroll container. Since the container is that stuck element, the element cannot select itself from inside the query. The workaround is to apply position: sticky to a wrapper and push every style you want to change down to the child.

.header-wrapper {
  container-type: scroll-state;
  container-name: getting-stuck;
  position: sticky;
  top: 0;
}

header {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  background-color: #40313D;
  padding: 0.5em;
  font-family: Tahoma;
}

The stuck setup lives on .header-wrapper, but styles cannot reach the container from within it — not even with :has() — so most styling belongs on the <header> element.

@container getting-stuck scroll-state(stuck: top) {
  header {
    padding: 0.25em;
    font-size: 0.8em;
    background-color: #40313D99;
    transition: 1s;
  }

  header .search ::is(input, button) {
    font-size: 0.8em;
  }

  header .logo {
    width: 1.5em;
    rotate: -375deg;
    transition: 1s;
  }
}

Resize loops and their fix

Changing a header child's size in a way that changes the header's own size can produce conflicting states: scrolling to the point where the header sticks triggers the size change, the smaller size pulls the header out of the stuck position, the stuck state cancels the size change, the header sticks again, and the cycle repeats. Even a small change can make it impossible to scroll past the stuck point. A transition can help, but it does not eliminate positions where the resize loops.

The fix is to set a height on the element that gets stuck (.header-wrapper above). Ideally that height is smaller than the header's final size when the header is being shrunk. A fixed height stops the element resizing when its content's size changes, at the cost of the header content overflowing. If overflow is unacceptable, change the size with transformations instead: a transformed element leaves a kind of placeholder in the DOM at its original position, and that placeholder determines the sticky position independently of whatever happens in the animation.

Styling snap targets with snapped

snapped applies styles once scroll snapping has engaged on an element. As with stuck, it is defined on the snapped element, not the scroll container; if snapping is not applied to the element, the feature is false and the query does not apply.

Snapping is first configured on the scroll container:

Note: As with most scrolling CSS, when the document's default scroll is in use it is the <html> element that scrolls, not the <body>.

html {
  scroll-snap-type: y mandatory;
}

The slide <div>s are what snap to the viewport size:

.slide {
  height: 100vh;  scroll-snap-align: start;
  scroll-snap-stop: always;
  container-type: scroll-state;
  container-name: getting-snappy;
}

As noted, the container type and name go on the snapped item; descendants of the slide are then restyled once it snaps:

@container getting-snappy scroll-state(snapped: y) {
  img {
    scale: 1.9;
    transition: 1s;
  }
}

And as with stuck, styles cannot be applied directly to the snapped element or container — only to its children.

Browser support