For years, if you wanted a page element to react to scrolling, you reached for JavaScript. A “back to top” button that appears once someone has read a little way down, a menu that tucks itself away and slides back when the visitor heads upwards, a header that changes once it sticks to the top of the screen: all of these meant scroll listeners, class toggling and a bit of performance worry.
The scroll-state() query moves a lot of that work into CSS. It lets a stylesheet ask the browser about the scroll situation of a container and apply styles only when the answer is yes.

Four Questions Your Stylesheet Can Now Ask
Despite the brackets, scroll-state() is not a function. It is a type of container query, used with @container in the same way as the style() query. There are four features it can check:
scrolled– which way the container was last scrolled (for exampletop,bottom,xory).scrollable– whether there is still content to scroll to in a given direction. Once the visitor reaches the end, it stops matching.stuck– whether aposition: stickyelement is currently pinned to an edge.snapped– whether an element with scroll snapping has snapped into place.
Each one also accepts logical values such as block-end and inline-start, which follow the page’s writing mode. That is handy for multilingual sites where “down” and “across” may not mean the same thing in every language.
A Back-to-Top Button Without JavaScript
To use the query, an element first has to be declared a scroll-state container. For the main page scroll, that element is html, not body. The example below hides a button off-screen and brings it into view while the visitor is moving down the page. In the same block, the site navigation slides away during downward scrolling and returns as soon as they scroll back up.
html {
container-type: scroll-state;
container-name: page;
}
.back-to-top {
position: fixed;
right: 1.5rem;
bottom: 1.5rem;
translate: 0 200%;
transition: translate 0.4s ease;
}
.site-nav {
transition: translate 0.4s ease;
}
@container page scroll-state(scrolled: bottom) {
.back-to-top { translate: 0 0; }
.site-nav { translate: 0 -100%; }
}
Because the styles only apply while the condition is true, the transition handles the return journey too. Scroll the other way and both elements glide back to their default positions.
The scrollable feature suits a different job: a small “scroll for more” arrow that shows while there is content below and disappears by itself once the visitor reaches the bottom.
Headers That Change Once They Stick
With stuck, the container is the sticky element itself rather than the scrolling area. The catch is that a container query cannot style its own container, so the usual approach is a sticky wrapper with the visual styling on an inner element.
.masthead {
position: sticky;
top: 0;
container-type: scroll-state;
container-name: masthead;
}
@container masthead scroll-state(stuck: top) {
.masthead-inner {
background: rgb(255 255 255 / 0.92);
box-shadow: 0 4px 16px rgb(0 0 0 / 0.12);
}
}
Scroll snapping follows the same pattern. Put the container on each snapping slide, then style what sits inside it, such as enlarging a photo or fading in a caption once that slide has settled into view.

Common Mistakes to Avoid
- Trying to style the container itself. Nothing inside the query can target the element that carries
container-type, and:has()won’t get around it. Style its children instead. - Shrinking a sticky header by changing its size. If the stuck state makes the header shorter, it can pull away from the edge, stop being stuck, grow back and stick again, causing a visible judder. Giving the sticky wrapper a fixed height, or scaling the content with a transform rather than changing padding and font size, avoids the loop.
- Using
bodyas the page container. For normal page scrolling, the element doing the scrolling ishtml. - Hiding something important behind the query. In browsers that don’t support it, the styles simply never apply. Make sure the default state still works, so the feature is a bonus rather than a requirement.
Questions Website Owners Ask
Does this mean we can drop JavaScript for scroll effects?
For simple show-and-hide behaviour, often yes. Anything that needs to remember state, fetch data or track exact scroll positions will still need a script.
Which browsers support it?
At the time of writing, Chromium-based browsers such as Chrome and Edge lead the way, and the scrolled feature arrived later than the other three. Check current support before relying on it, and treat it as progressive enhancement.
Is it better for performance?
Letting the browser handle scroll conditions natively generally avoids the work of running scroll listeners on every movement, which can help on lower-powered phones.
What about visitors who dislike motion?
Wrap the transitions in a prefers-reduced-motion media query so elements still appear and disappear, just without sliding animations. Small touches like that are exactly what make a business website feel polished rather than gimmicky.











