Sticky stack — pd-sticky-stack + pd-sticky
See it live in the styled storefront › — the collection toolbar rides the auto-hide masthead's slide frame by frame as you scroll.
pd-sticky-stack is the missing primitive for pages with several sticky bars stacked on top of each other — a masthead, a collection toolbar, section headings — where a shallower bar must never overlap a deeper one, and deeper bars must ride up to fill the gap the moment a shallower one (like an auto-hide pd-header) slides away. It is entirely non-interactive: no open state, no commands, no keyboard map. The stack measures; you style.
Anatomy
<pd-sticky-stack> <!-- 1 -->
<pd-sticky level="0"> <!-- 2 -->
<header class="site-header">…pd-header masthead…</header>
</pd-sticky>
<pd-sticky level="1" class="collection-toolbar"> <!-- 3 -->
Filters / sort
</pd-sticky>
<section>
<pd-sticky level="2"><h2>Cleansers</h2></pd-sticky> <!-- 4 -->
<ul>…products…</ul>
</section>
<section>
<pd-sticky level="2"><h2>Moisturizers</h2></pd-sticky>
<ul>…products…</ul>
</section>
</pd-sticky-stack>- The coordinator. Owns no state of its own — it queries its descendant
pd-stickymembers live, in document order, on every recompute pass. There is no member registry to keep in sync. - The shallowest member,
level="0". Nothing sticks above it, so its--pd-sticky-topis always0px. Wrapping apd-headermasthead here (see the auto-hide conjunction recipe below) is the canonical use of level 0. level="1"sticks below whatever level-0 member is currently stuck — its offset is that member's measured height, kept live as the masthead resizes or slides.level="2"members live inside ordinary<section>s; they don't need to be siblings of the shallower members, only descendants of the samepd-sticky-stack. Each section's heading sticks at the toolbar's bottom edge while its section is in view, and un-sticks (making room for the next section's heading) once the section scrolls past.
level is the only attribute. There's no required nesting shape beyond "descendant of a pd-sticky-stack" — flat or deeply wrapped, it doesn't matter, since members are found by query, not by parent-child position.
What it does — measured geometry out, styling in
Per the library's hard rule, neither component sets position, top, or z-index — you opt a member into sticky positioning yourself:
pd-sticky {
position: sticky;
top: var(--pd-sticky-top, 0px);
}On every recompute pass (see triggers below) the stack walks its members in document order and, for each one:
- Sums the measured visible-height contribution of every currently-stuck member at a shallower level above it, and writes that sum as
--pd-sticky-topon the member viaapplyOffset(). A member's own contribution is the maxgetBoundingClientRect().bottomacross its element children (falling back to its own box if it has none) — child rects include transforms, so a masthead sliding out mid-animation shrinks its member's contribution frame by frame, and everything below it follows the slide instead of snapping at the end. - Decides whether the member is currently stuck: its top edge has reached the offset (± 1px epsilon) and its bottom edge is still past it — a member fully pushed out by its section's sticky containment keeps
top <= offsetforever but has stopped occupying the line, so it no longer counts. Togglesdata-stuck/ firespd:stick/pd:unstickviasetStuck()only on an actual transition. - Same-level members replace each other — they never stack. A later same-level member's contribution simply overwrites the earlier one's in the running total; CSS sticky containment inside each one's own section already provides the natural push-out as you scroll from one section to the next.
- A shallower re-stick resets deeper chains below it. If a new level-0 member becomes stuck, any level-1/2/… contribution left behind by whatever was stuck before it is discarded — the chain rebuilds from the new shallower anchor down.
The stack also publishes the total currently-stuck height as --pd-stack-height, on both itself and document.documentElement — this is what drives the scroll-padding-top recipe in the accessibility section below.
Recompute triggers: scroll (rAF-throttled, passive window listener — a burst of scroll events collapses to one recompute per frame), a member's size changing (one shared ResizeObserver across all members), a member connecting or disconnecting (each member asks its stack directly — there's no automatic registry), a member's own level attribute changing, and continuously, frame by frame, while any member's subtree has a running CSS transition or animation (delegated transitionrun/transitionend/animationstart/animationend/*cancel listeners arm a temporary rAF loop) — this is what keeps offsets tracking an auto-hiding masthead's slide instead of jumping to the final value only once it finishes.
A pd-sticky with no ancestor pd-sticky-stack warns once and stays inert at --pd-sticky-top: 0px. A pd-sticky-stack nested inside another one warns and stays fully inert — its own members are never measured (unsupported in v1).
Attributes
| Attribute | Element | Type | Default | Notes |
|---|---|---|---|---|
level | pd-sticky | non-negative integer | 0 | Defines the hierarchy: shallower (lower-numbered) stuck members push deeper ones down; same-level members replace each other. Non-integer, negative, or missing values fall back to 0. Changing it at runtime re-derives the member's offset immediately, without waiting for the next scroll. |
pd-sticky-stack takes no attributes of its own.
Published custom properties
Not styling — measured geometry the stack/member write for your CSS to consume (§3 amendment to the "no inline styles beyond hidden/scroll-lock" rule, same convention as Radix/Base UI's --*-height variables).
| Property | Written on | Value | Notes |
|---|---|---|---|
--pd-sticky-top | each pd-sticky member | px offset, e.g. 40px | The cumulative visible height of currently-stuck shallower-level members above this one. Write-deduped at 0.1px granularity — the per-frame recompute loop calls applyOffset() every frame, and most frames produce an unchanged value. |
--pd-stack-height | the pd-sticky-stack itself and document.documentElement | px, e.g. 150px | The total currently-stuck height at the viewport top. Published on documentElement too so it's reachable from anywhere in your page's CSS, not just inside the stack's own subtree — see the scroll-padding-top recipe below. Removed from documentElement on disconnect. |
Methods
These exist for the coordinator to drive its members — call them yourself only if you're implementing a custom layout that bypasses pd-sticky-stack's own recompute loop (rare; prefer just nesting the member inside a stack).
| Member | On | Signature | Notes |
|---|---|---|---|
applyOffset(px) | pd-sticky | (px: number) => void | Coordinator-facing. Sets --pd-sticky-top, rounded and write-deduped at 0.1px. Called by the stack's recompute() every pass. |
setStuck(stuck) | pd-sticky | (stuck: boolean) => void | Coordinator-facing. Toggles data-stuck and fires pd:stick/pd:unstick, but only on an actual transition (calling it with the current value again is a no-op). Called by the stack's recompute(). |
visibleBottom() | pd-sticky | () => number | The member's own visible-height contribution — max getBoundingClientRect().bottom across its element children, falling back to its own box if it has none. Read-only helper; the stack calls it, you generally don't need to. |
recompute() | pd-sticky-stack | () => void | Re-walks all members and republishes their offsets/data-stuck/--pd-stack-height. Public because members call it directly on connect/disconnect and level changes (there's no member registry to react automatically) — call it yourself only after a DOM change the stack has no other way to observe (e.g. you swapped a member's children without triggering a ResizeObserver callback, such as replacing text synchronously without a layout-affecting size change). |
Commands
Neither component defines a command vocabulary. Nothing targets a pd-sticky/pd-sticky-stack via commandfor, and neither listens for command events — there's no author-triggered open/close here to invoke.
Events
| Event | Cancelable | On | When | detail |
|---|---|---|---|---|
pd:stick | no | pd-sticky | The member transitions from un-stuck to stuck. | { level } |
pd:unstick | no | pd-sticky | The member transitions from stuck to un-stuck. | { level } |
Fired only on the transition — repeated recomputes while a member's stuck state is unchanged never re-fire. level is the member's own level at the moment of the transition (read from the level attribute, not cached from connect), useful for a listener bound once at the stack level that needs to tell which tier changed without also inspecting the target.
Keyboard
No keyboard surface. pd-sticky and pd-sticky-stack add no keydown listener, define no key handling, and are not part of the invoker-command family — they measure and position, nothing else. Everything inside a member keeps its native or pd-* keyboard behavior untouched; a pd-nav inside a level-0 masthead handles its own arrow-key/Escape map exactly as it would outside a stack.
Accessibility
Managed automatically: nothing — this module has no interactive semantics of its own to manage. Its accessibility contract is entirely about not getting in the way of the content and controls it positions.
You must provide:
scroll-padding-topkeyed to--pd-stack-height. This is the headline recipe and the reason--pd-stack-heightis published ondocument.documentElementand not just the stack element: without it, an in-page anchor jump (#cleansers) or a focus-scroll target (a skip link, afocus()call,:target) lands underneath the currently-stuck bars, hiding the very heading or control the user just navigated to. One rule, page-wide, fixes every case at once:csshtml { scroll-padding-top: var(--pd-stack-height, 0px); }This is normative for these docs (SPEC §5.7) and directly addresses WCAG 2.4.3 (focus order) — a keyboard or assistive-tech user who jumps to a target must actually be able to see it land.
scroll-padding-topaffects the browser's own scroll-into-view behavior (anchor navigation,Element.scrollIntoView(),:target, and native focus-scroll onfocus()), so this one line covers all of them without per-target math.z-index, deliberately layered. The stack doesn't setz-indexon anything — assign it yourself, and keep it monotonic withlevel(shallower levels sit visually on top of deeper ones, matching the fact that they scroll-cover them):pd-sticky[level='0'] { z-index: 30; },level='1'lower, and so on. Getting this backwards doesn't break the offset math (that's purely geometric) but does mean a "deeper" bar can visually paint over a "shallower" one it's supposed to sit under.Focus outlines that survive the stack. A sticky member painting
background/box-shadowto separate itself from scrolled-under content must not clip a focused descendant's outline —overflow: visibleon the member (the default) and outline styles that aren'toutline: nonewithout a replacement are enough; nothing here is special beyond the usual focus-visible hygiene. More importantly: a sticky bar must never trap focus, or obscure a control the moment it receives focus. Since these components never sethiddenor move focus, this mostly falls out automatically — but if you combine a member with an auto-hide masthead (below), make sure that masthead's own focus/open guards (SPEC §5.6 —pd-headernever hides while it contains focus or has an open descendant) are intact, since a level-0 member that vanished mid-interaction would otherwise carry its whole offset contribution away with it.Landmark/heading semantics inside members, same as anywhere else —
pd-stickyis a plain, role-less wrapper. A<h2>inside a level-2 member, a<nav aria-label>inside a level-0 masthead, etc. are your responsibility, unaffected by being inside a sticky member.
Styling — vanilla CSS
The complete recipe: opt each member into position: sticky, layer by level, and wire the page-wide scroll-padding rule.
html {
scroll-padding-top: var(--pd-stack-height, 0px);
}
pd-sticky-stack {
display: grid;
}
pd-sticky {
display: block;
position: sticky;
top: var(--pd-sticky-top, 0px);
background: canvas;
}
pd-sticky[level='0'] {
z-index: 30;
}
pd-sticky[level='1'] {
z-index: 20;
}
pd-sticky:not([level='0']):not([level='1']) {
z-index: 10;
}
/* Optional: a visual cue while a member is actually pinned, independent of
its `level` — useful for a hairline border that only appears once stuck. */
pd-sticky[data-stuck] {
border-block-end: 1px solid color-mix(in oklab, canvasText 12%, transparent);
}Auto-hide masthead conjunction
Wrapping a pd-header as the level-0 member is the canonical pairing: the masthead slides up and down under its own scroll-direction logic, and the stack's per-frame recompute (armed by pd-header's own CSS transition firing transitionrun/transitionend) follows the slide, so level-1/2 members ride up to fill the gap in step with the animation instead of jumping once it settles.
<pd-sticky-stack>
<pd-sticky level="0">
<pd-header threshold="8" min-y="120" role="banner" class="site-header">
<div class="primary-bar">
<a href="/">Brand</a>
<nav aria-label="Main"><!-- pd-nav … --></nav>
</div>
</pd-header>
</pd-sticky>
<pd-sticky level="1" class="collection-toolbar">Filters / sort</pd-sticky>
</pd-sticky-stack>/* pd-header owns its own position: sticky / transform per its own docs — the
level-0 pd-sticky wrapping it only needs to not fight that. It stays a
plain block box; the stack still measures its (pd-header's) child rect for
--pd-stack-height, since a member's contribution comes from its element
children, not the member's own box. */
pd-sticky[level='0'] {
position: static;
z-index: 30;
}
.site-header {
position: sticky;
inset-block-start: 0;
z-index: 30;
transition: transform 250ms ease-out;
}
.site-header[data-state='hidden'] {
transform: translateY(-100%);
}
pd-sticky[level='1'] {
z-index: 20;
}Styling — Tailwind
Grid-first, no nested flex for the layered z-index scale:
<pd-sticky-stack class="grid">
<pd-sticky
level="0"
class="sticky top-[var(--pd-sticky-top,0px)] z-30 block bg-white
data-[stuck]:border-b data-[stuck]:border-gray-200"
>
<header class="site-header">…pd-header masthead…</header>
</pd-sticky>
<pd-sticky
level="1"
class="sticky top-[var(--pd-sticky-top,0px)] z-20 block bg-white
data-[stuck]:border-b data-[stuck]:border-gray-200"
>
Filters / sort
</pd-sticky>
<section>
<pd-sticky level="2" class="sticky top-[var(--pd-sticky-top,0px)] z-10 block bg-white">
<h2>Cleansers</h2>
</pd-sticky>
</section>
</pd-sticky-stack>/* tailwind.config / global CSS — the scroll-padding recipe isn't a per-class
utility, since it's a page-wide `html` rule keyed to the published property. */
html {
scroll-padding-top: var(--pd-stack-height, 0px);
}top-[var(--pd-sticky-top,0px)] is Tailwind's arbitrary-value syntax reading the same custom property the vanilla recipe uses directly — there's no Tailwind-specific offset utility here, since the value is computed per-instance by the stack, not a design-token scale step. data-[stuck]:border-b targets the boolean data-stuck presence attribute the same way data-[open] is used elsewhere in this library.
Live demo
Like pd-header, pd-sticky-stack listens to the whole page's window scroll position, not a scroll container — scrolling an inner overflow: auto box never fires a window scroll event, so a demo confined to a small scrollable element on this page can't drive it. The block below is real pd-sticky-stack/pd-sticky markup, positioned inside a tall filler so that scrolling this documentation page is what drives the recompute loop.
Scroll down slowly through the filler sections: the level-0 bar sticks first, then the level-1 toolbar sticks directly under it (offset by the level-0 bar's own height), then each level-2 section heading sticks under the toolbar in turn, replacing the previous section's heading as you cross into the next one.