CSS scroll-state() Explained: Build Sticky Headers and Scroll-Anerkennung UI Without JavaScript

November 20, 2026

What it is

scroll-state() is a new CSS container query function. It lets you ask a scrolling container about its current scroll condition, then style descendants without listening to scroll events in JavaScript.

modern website navigation header

The most useful case is the sticky stuck state. A sticky element can be visually resting at the top or bottom of its scroll container. With scroll-state(), you can add a border, stronger background, elevation, or a compact layout only while that state is true.

You can also query scroll direction in supporting engines. Direction is good for show/hide navigation patterns; stuck is better for state changes such as “this table header is pinned.”

sticky table interface

Syntax

The important detail is that scroll-state() belongs to @container. First, the actual scrolling element must establish scroll-state containment:

html {
  container-type: scroll-state;
}

Then query that container:

@container scroll-state(stuck: top) {
  .site-header {
    border-bottom: 1px solid #d7dce3;
    background: rgba(255, 255, 255, 0.92);
  }
}

When the scroller is the document, use html. The browser queries the viewport scroller, and the rule matches while a sticky header is stuck to its top edge.

Named scroll-state containers

For a component with its own overflow, name the scrolling element and set the same containment type:

.panel-scroll {
  overflow: auto;
  container-name: panel;
  container-type: scroll-state;
}
@container panel scroll-state(stuck: top) {
  .panel-header {
    background: #fff;
    border-bottom: 1px solid #d7dce3;
  }
}

Do not put the containment on the sticky child. The query is answered by the scroll container that contains the sticky element.

Header demo

This complete demo uses the page scroller. The header starts transparent and gains a readable treatment after the page is scrolled and the sticky header is pinned to the top.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>scroll-state header demo</title>
  <style>
    * { box-sizing: border-box; }

    html {
      container-type: scroll-state;
      scroll-behavior: smooth;
    }

    body {
      margin: 0;
      font-family: system-ui, sans-serif;
      background: #f6f7f9;
      color: #172033;
    }

    .site-header {
      position: sticky;
      top: 0;
      z-index: 10;
      min-height: 72px;
      display: flex;
      align-items: center;
      padding: 0 24px;
      background: #f6f7f9;
      border-bottom: 1px solid transparent;
      transition: background 200ms ease, border-color 200ms ease, min-height 200ms ease;
    }

    .nav {
      width: min(960px, 100%);
      margin: 0 auto;
      display: flex;
      align-items: center;
      justify-content: space-between;
      gap: 16px;
    }

    .brand {
      font-weight: 800;
      text-decoration: none;
      color: #172033;
    }

    .nav a:not(.brand) {
      color: #33415c;
      text-decoration: none;
      margin-left: 18px;
    }

    .hero {
      width: min(960px, calc(100% - 48px));
      margin: 0 auto;
      padding: 96px 0 64px;
    }

    main {
      width: min(960px, calc(100% - 48px));
      margin: 0 auto 120px;
      font-size: 18px;
      line-height: 1.7;
    }

    @supports (container-type: scroll-state) {
      .site-header {
        background: rgba(246, 247, 249, 0.72);
      }

      @container scroll-state(stuck: top) {
        .site-header {
          min-height: 58px;
          background: rgba(255, 255, 255, 0.94);
          border-bottom-color: #d7dce3;
          backdrop-filter: blur(12px);
        }
      }
    }

    @media (prefers-reduced-motion: reduce) {
      html { scroll-behavior: auto; }
      .site-header { transition: none; }
    }
  </style>
</head>
<body>
  <header class="site-header">
    <nav class="nav" aria-label="Main navigation">
      <a class="brand" href="#top">Acme</a>
      <div>
        <a href="#features">Features</a>
        <a href="#pricing">Pricing</a>
        <a href="#docs">Docs</a>
      </div>
    </nav>
  </header>

  <section class="hero" id="top">
    <h1>Scroll-aware UI in CSS</h1>
    <p>Scroll down to see the sticky header respond.</p>
  </section>

  <main id="features">
    <p>Add enough content here to make the document scroll. Repeat sections, documentation text, cards, or product detail blocks.</p>
    <p style="height: 120vh;">More page content...</p>
  </main>
</body>
</html>

Here the queried scroll container is the document scroller established by html. The .site-header is the sticky child, and the rule applies while it is stuck at top: 0.

Component demos

Sticky table header

For an inner table, the scrolling element must create the containment context.

<div class="table-scroll">
  <table>
    <thead>
      <tr><th>Name</th><th>Status</th></tr>
    </thead>
    <tbody>
      <tr><td>Ava</td><td>Active</td></tr>
    </tbody>
  </table>
</div>
.table-scroll {
  height: 320px;
  overflow: auto;
  container-name: table;
  container-type: scroll-state;
  border: 1px solid #d7dce3;
  border-radius: 12px;
}

th {
  position: sticky;
  top: 0;
  background: #f1f4f8;
  text-align: left;
}

@container table scroll-state(stuck: top) {
  th {
    background: #ffffff;
    border-bottom: 2px solid #33415c;
  }
}

The query targets the .table-scroll container, not the table or th. The sticky th elements get the enhanced style while pinned to that container’s top.

Bottom action bar

A bottom bar uses stuck: bottom:

.sheet {
  height: 420px;
  overflow: auto;
  container-name: sheet;
  container-type: scroll-state;
}

.action-bar {
  position: sticky;
  bottom: 0;
  background: #fff;
  padding: 16px;
  border-top: 1px solid transparent;
}

@container sheet scroll-state(stuck: bottom) {
  .action-bar {
    border-top-color: #d7dce3;
    box-shadow: 0 -10px 30px rgba(20, 30, 50, 0.12);
  }
}

Use stuck when the UI should reflect position. Use scroll-direction when the UI should react to movement, such as hiding a bar while scrolling down and revealing it while scrolling up. Direction changes continuously; stuck is usually more stable for accessible controls.

Nested scroll containers

Be explicit with named containers when scrollers nest. An unnamed query can resolve against the nearest eligible ancestor, which may not be the scroller you expect. Name panels, sheets, and tables, then query those names.

A sticky element is also constrained by its containing block. If a parent has overflow: hidden, the sticky behavior may appear broken even though the query is written correctly.

Support and fallback

Scroll-state container queries were introduced in Chrome and Edge 133. Support in other browsers changes quickly, so check Can I Use, MDN, and browser release notes before shipping widely.

The safest pattern is progressive enhancement: make the default design fully usable, then add the scroll-state-dependent treatment only where supported.

.site-header {
  position: sticky;
  top: 0;
  background: #fff;
  border-bottom: 1px solid #d7dce3;
}

@supports (container-type: scroll-state) {
  .site-header {
    background: rgba(255, 255, 255, 0.9);
  }

  @container scroll-state(stuck: top) {
    .site-header {
      border-bottom-color: #9aa7ba;
      backdrop-filter: blur(12px);
    }
  }
}

Notice the default header is opaque and already has a divider. If scroll-state() is unavailable, the page still works and content never hides under a transparent bar.

If you want a genuinely transparent initial header, reserve space in normal flow or give the first section enough top padding. Do not rely on JavaScript to fix overlap. A simple rule is to start with an opaque header, then soften it inside the @supports block.

Accessibility and motion

Do not communicate state with shadow alone. Add a border, background contrast, underline, or text treatment. That helps users who cannot easily perceive elevation and keeps controls readable when focus rings appear over sticky bars.

Check focused links, buttons, and skip links inside sticky regions. A focused control should never be clipped or lose contrast against scrolling content.

Keep transitions short and respect reduced motion:

@media (prefers-reduced-motion: reduce) {
  .site-header,
  .action-bar {
    transition: none;
  }
}

Common mistakes

</tbody> </table>

Once the containment boundary is set on the real scroller, most demos fall into place. The CSS owns the visual state, and JavaScript can stay out of the scroll path.

WrongCorrect
Putting container-type: scroll-state on the sticky header. Put it on the scrolling ancestor, such as html or an overflow: auto panel.
Writing a normal media query for sticky state. Use @container scroll-state(...).
Setting only container-name on a component. Set both container-name and container-type: scroll-state.
Using direction to style a pinned table header. Use stuck: top; use direction for movement-based hiding.
Defaulting to a transparent header without spacing. Use an opaque default and enhance only inside @supports.