Auto-hide header — pd-header
See it live in the styled storefront › — scroll down and the masthead slides away; scroll up anywhere and it returns.
pd-header is a scroll-driven state machine, not a disclosure. It doesn't extend the open/close family (pd-disclosure, pd-nav-panel, pd-drawer) — it has no open attribute, no commands, no hidden toggling. It owns exactly one decision: should the header currently be visible or hidden, expressed as data-state="visible"|"hidden" plus a data-at-top flag, driven by a single passive, rAF-throttled window scroll listener.
Anatomy
<pd-header threshold="8" min-y="120"> <!-- 1 -->
<div class="announcement">Free shipping over $50</div> <!-- 2 -->
<div class="primary-bar">
<a href="/">Brand</a>
<nav aria-label="Main">
<pd-nav>…</pd-nav> <!-- 3 -->
</nav>
</div>
</pd-header>- The only custom element on the page.
pd-headerwraps whatever bars/nav you already have; it adds no markup of its own. - Ordinary content. An announcement bar hides along with everything else in the header — there is no special-casing inside
pd-headerfor "this row should stay." - Composes directly with
pd-nav— an open mega panel inside apd-headeris an "open descendant" and keeps the whole header pinned visible (see the focus/open guard below).
The state machine
On connect: always data-state="visible", data-at-top set from the current scrollY, no pd:show fires (nothing transitioned — there's no "before" state to compare against). From then on, every scroll event schedules at most one requestAnimationFrame callback (a #ticking flag collapses a scroll burst into a single frame; falls back to a synchronous decision if rAF is unavailable) which runs this decision tree:
- At the top (
scrollY <= 2): always visible,data-at-topset, baseline (#lastY) reset. Whatever happened below the fold is irrelevant once you're back at the top. - Delta below
threshold: ignored — but not lost. The baseline is only committed once a real decision is made, so several small deltas (momentum scrolling, a trackpad's fractional events) accumulate against the same baseline until they cross the threshold together. - Scrolling up (
delta < 0): always shows, unconditionally — regardless of lock state, position, ormin-y. An up-scroll is read as "the user wants to see the header again." - Scrolling down past
min-y, and not locked: hides. - Locked (
#isLocked()): a down-scroll that would otherwise hide is suppressed. Locked = contains focus, has an open descendant, or carriespinned.
data-at-top and data-state are independent — a header can be data-state="visible" while not at the top (it just showed on an up-scroll) or data-at-top while also mid-transition.
Why motion lives in CSS
Per the library's hard rule (no styling from JS beyond hidden/scroll-lock), pd-header never sets transform, transition, or any visual property. It writes data-state and data-at-top and nothing else — no hidden attribute either, since a translated-off-screen header is still in the accessibility tree and still occupies its place for layout purposes (its content is meant to still be reachable, just not currently visible — see the focus guard below).
Two consequences follow:
- You own the entire animation. Slide, fade, no motion at all on mobile but slide on desktop — none of it requires touching the component.
prefers-reduced-motionis a pure CSS media query on your side, not a JS branch inside the library. pd:show/pd:hidefire at the moment of the logical state flip, not after any animation settles. This is a deliberate contrast withpd:opened/pd:closedon the disclosure family, which wait forafterAnimations()because those components must applyhiddenonly once the exit animation finishes.pd-headerhas no such handoff — there's nothing to wait for, so the event and the attribute flip are simultaneous.
pin() / unpin()
Independent of the scroll machine, pinned (attribute, reflected as the pinned property) forces visibility on regardless of scroll direction or position:
const header = document.querySelector('pd-header')
header.pin() // same as header.pinned = true / setAttribute('pinned', '')
header.unpin() // same as header.pinned = falseSetting pinned on an already-hidden header shows it immediately — not on the next scroll frame — because attributeChangedCallback calls #setVisible(true) synchronously when pinned transitions from absent to present while the header is hidden. Typical use: pin the header while a mobile drawer or search overlay that lives outside the header's own DOM is open (an in-header overlay is already covered automatically by the open-descendant guard below):
const drawer = document.querySelector('pd-drawer')
drawer.addEventListener('pd:opened', (event) => {
if (event.target === drawer) header.pin()
})
drawer.addEventListener('pd:closed', (event) => {
if (event.target === drawer) header.unpin()
})The target checks exclude bubbling lifecycle events from nested disclosures.
Focus / open-descendant guards
pd-header never hides while it's "in use," full stop — this is the component's core accessibility guarantee (WCAG 2.4.3 focus order, 2.1.1 keyboard access): a control a keyboard user is actively interacting with must not slide out from under them mid-interaction. Three independent conditions each set the lock:
- Contains focus. Tracked explicitly via
focusin/focusout(not:focus-withinpolling, which can miss focus moving to a hidden descendant's sibling within a single tick). - Has an open descendant.
this.querySelector('[open], [data-state="open"]')— this is whypd-nav-panel,pd-disclosure, andpd-drawer(all of which setopen/data-state="open") are recognized automatically with zero wiring. A hand-rolled dropdown using a different convention won't be seen by this check — mirrordata-state="open"on it, or callpin()/unpin()yourself from its open/close handlers. pinned. The manual override above.
For scroll decisions the lock only ever suppresses a hide-in-progress. Focus is handled more strongly: the focusin listener also checks whether the header is currently hidden, and if so reveals it immediately — data-state="visible" flips and pd:show fires synchronously, before any scroll event. A skip link, find-in-page hit, or focus restore landing in the header must never leave focus on an off-screen control.
Attributes
| Attribute | Type | Default | Notes |
|---|---|---|---|
threshold | number (px) | 8 | Minimum accumulated scroll delta before a direction change is committed. Non-finite or negative values fall back to the default. |
min-y | number (px) | the element's own offsetHeight, read live (not cached at connect) | scrollY must exceed this before a down-scroll is allowed to hide the header — i.e. it won't hide while its own height is still on screen, by default. |
pinned | boolean, reflected | absent | See pin()/unpin() above. The only attribute with a matching JS property. |
threshold and min-y are attribute-only — there is no header.threshold/header.minY property; reconfigure them with setAttribute.
Properties & methods
| Member | Signature | Notes |
|---|---|---|
pinned | boolean (get/set) | Reflects the pinned attribute. |
pin() | () => void | pinned = true. |
unpin() | () => void | pinned = false. |
There is no open/show()/hide()/toggle() — pd-header is not part of the pd-disclosure family despite superficially having a visible/hidden binary. Visibility is scroll-derived, not author-commanded (except via pinned).
Commands
pd-header defines no command vocabulary. Nothing targets it via commandfor, and it does not listen for command events at all — there's no --pd-* command that makes sense for a state machine with no author-triggered open/close. Use pin()/unpin() (or the pinned attribute) for programmatic control instead.
Events
| Event | Cancelable | When | detail |
|---|---|---|---|
pd:show | no | Visibility flips to visible (up-scroll, reaching the top, focus entering a hidden header, or pin()/pinned on a hidden header). | { y } |
pd:hide | no | Visibility flips to hidden (down-scroll past min-y, unlocked). | { y } |
Fired only on an actual transition — repeated down-scrolling while already hidden does not re-fire pd:hide, and the initial mount never fires pd:show (see the state machine above). y is window.scrollY at the moment of the decision.
Keyboard
pd-header adds no keydown listener and defines no bespoke key handling of its own.
| Key | Context | Behavior |
|---|---|---|
Tab / Shift+Tab | any focusable descendant | Native browser focus movement. Entering the header sets the internal focus lock described above (suppresses the next hide decision) — and if the header was already hidden, reveals it immediately (data-state="visible", pd:show). |
| (all other keys) | inside the header | Entirely native to whatever you put inside — a pd-nav's own keyboard map, a plain <button>'s Enter/Space, etc. pd-header is a transparent wrapper for keyboard purposes. |
Accessibility
Managed automatically:
- The "never disappear while in use" guarantee above (WCAG 2.4.3 / 2.1.1) — this is the component's accessibility contract; everything else follows from it.
pin()/unpin()as an escape hatch for cases the automatic guards can't see.
You must provide:
- Landmark semantics.
pd-headeris an unknown custom element with no implicit ARIA role — addrole="banner"directly on it if it represents the page's one main header (omit if it's a repeated/secondary bar, per thebannerrole's "one per page" convention), or nest a native<header>inside if you'd rather not set a role by hand. - All motion. The component sets no
transform/transition— see the recipe below. - The open-descendant convention. Any custom widget inside the header that isn't a
pd-*element needsdata-state="open"mirrored onto it (or manualpin()/unpin()) for the lock to see it.
Styling — vanilla CSS
The complete translateY recipe: continuous transform driven by data-state, no keyframe/exit choreography needed (unlike the disclosure family, pd-header never applies hidden, so there's no afterAnimations() handshake to satisfy — a plain transition is enough).
pd-header {
position: sticky;
inset-block-start: 0;
z-index: 30;
display: grid;
grid-template-rows: auto auto; /* announcement row, primary-bar row */
transition: transform 250ms ease-out;
}
pd-header[data-state='hidden'] {
transform: translateY(-100%);
}
/* Grid placement inside the primary bar: brand | nav | actions, no nested flex */
.primary-bar {
display: grid;
grid-template-columns: auto 1fr auto;
align-items: center;
gap: 1rem;
padding-inline: 1rem;
padding-block: 0.75rem;
}
/* Optional: only show a background/border once scrolled, so the header can
sit transparent over a hero at the very top of the page. */
pd-header:not([data-at-top]) {
background: canvas;
border-block-end: 1px solid color-mix(in oklab, canvasText 12%, transparent);
}
@media (prefers-reduced-motion: reduce) {
pd-header {
transition: none;
}
}Styling — Tailwind
<pd-header
threshold="8"
min-y="120"
role="banner"
class="sticky top-0 z-30 grid grid-rows-[auto_auto] transition-transform duration-[250ms] ease-out
data-[state=hidden]:-translate-y-full motion-reduce:transition-none
[&:not([data-at-top])]:bg-white [&:not([data-at-top])]:border-b [&:not([data-at-top])]:border-gray-200"
>
<div class="announcement">Free shipping over $50</div>
<div class="grid grid-cols-[auto_1fr_auto] items-center gap-4 px-4 py-3">
<a href="/">Brand</a>
<nav aria-label="Main"><!-- pd-nav … --></nav>
</div>
</pd-header>data-[state=hidden]:-translate-y-full and motion-reduce:transition-none are both direct Tailwind arbitrary/built-in variants — no custom @keyframes needed here, since this is a continuous transform/transition pair rather than an enter/exit animation. data-at-top is a bare boolean attribute (no value), so its positive case is data-[at-top]:…; the arbitrary selector variant [&:not([data-at-top])]:… above targets its absence directly rather than relying on a value-based comparison.
Live demo
pd-header listens to the whole page's window scroll position, not a scroll container — so a demo confined to a small scrollable box inside this page cannot trigger it (scrolling an inner overflow: auto element never changes window.scrollY). The block below is real pd-header markup, sticky-positioned inside a tall filler so that scrolling this documentation page is what drives it.
By the time you've scrolled down this far, the header below has likely already committed a "hide" decision from the scrolling you did to get here (its listener has been running since the page loaded). Scroll up a little first to bring it into "visible," then scroll down slowly through the filler blocks to watch it slide away past its own height, and back up to bring it back.