Design Atlas
한국어
{} Modern CSS & web APIs

Scroll-State Container Queries

스크롤 상태 쿼리

A container query that asks about scroll-related state directly — whether an element is currently stuck, snapped, or scrollable.

Also known as: @container scroll-state()stuck query
···
html
<div class="wrap">
  <div class="badge" id="badge"><svg viewBox="0 0 10 10"><path id="bpath" d="M1.5 5.2l2.6 2.6L8.5 2.4" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round"/></svg><span id="btext">확인 중</span></div>
  <div class="scroller" id="scroller">
    <div class="head" id="head">헤더 (스크롤하면 붙음)</div>
    <div class="filler">위 내용</div><div class="filler">위 내용</div><div class="filler">아래로 스크롤</div>
    <div class="filler">계속</div><div class="filler">계속</div><div class="filler">끝</div>
  </div>
</div>
css
.wrap{position:relative;width:min(260px,92%);height:100%;display:grid;place-items:center}
.scroller{width:100%;height:140px;overflow-y:auto;border:1px solid var(--line);border-radius:10px;container-type:scroll-state}
.head{position:sticky;top:0;padding:8px 10px;font-size:11px;font-weight:700;background:var(--surface);color:var(--fg);border-bottom:1px solid var(--line);transition:box-shadow .2s}
@container scroll-state(stuck: top){ .head{ box-shadow:0 4px 10px rgba(0,0,0,.16) } }
.head.fallback-stuck{box-shadow:0 4px 10px rgba(0,0,0,.16)}
.filler{padding:16px 10px;font-size:11px;color:var(--muted);border-bottom:1px dashed var(--line)}
.badge{position:absolute;top:0;right:0;display:flex;align-items:center;gap:5px;padding:4px 9px;border-radius:999px;font-size:10px;font-weight:700;background:var(--bg);border:1px solid var(--line);color:var(--accent-3);z-index:2}
.badge.no{color:var(--accent-2)}
.badge svg{width:9px;height:9px}
js
const ok = CSS.supports('container-type', 'scroll-state');
const b=document.getElementById('badge'),p=document.getElementById('bpath'),t=document.getElementById('btext');
b.classList.toggle('no', !ok);
p.setAttribute('d', ok ? 'M1.5 5.2l2.6 2.6L8.5 2.4' : 'M2 2l6 6M8 2l-6 6');
t.textContent = ok ? '스크롤 상태 쿼리 지원됨' : '미지원 · IO 폴백';
const scroller = document.getElementById('scroller'), head = document.getElementById('head');
if (!ok) {
  const sentinel = document.createElement('div'); sentinel.style.height = '1px'; scroller.insertBefore(sentinel, head);
  new IntersectionObserver(([e]) => head.classList.toggle('fallback-stuck', !e.isIntersecting), { root: scroller, threshold: 1 }).observe(sentinel);
}
let dir = 1;
setInterval(() => { scroller.scrollTop += dir * 40; if (scroller.scrollTop <= 0 || scroller.scrollTop >= scroller.scrollHeight - scroller.clientHeight) dir *= -1; }, 900);

Detecting the exact moment a `position: sticky` header "sticks" to the top — to add a shadow, say — has always needed JS, since CSS had no way to know whether it was currently stuck. The usual approach was an IntersectionObserver watching a sentinel element.

`@container scroll-state(stuck: top)` asks that question directly, in container-query syntax. Give the parent `container-type: scroll-state` and children can restyle based on stuck/snapped/scrollable state inside a scroll container. Where scroll-driven animation handles continuous scroll progress, this handles discrete state changes caused by scrolling — the two complement each other.

Check caniuse/MDN baseline for support. Without it, an IntersectionObserver watching a sentinel element and toggling a class remains the standard fallback.

When to use

Adding a shadow when a sticky header sticks, or enabling a button based on scroll-snap state.