Skip to content

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 ​

html
<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>
  1. The only custom element on the page. pd-header wraps whatever bars/nav you already have; it adds no markup of its own.
  2. Ordinary content. An announcement bar hides along with everything else in the header — there is no special-casing inside pd-header for "this row should stay."
  3. Composes directly with pd-nav — an open mega panel inside a pd-header is 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:

  1. At the top (scrollY <= 2): always visible, data-at-top set, baseline (#lastY) reset. Whatever happened below the fold is irrelevant once you're back at the top.
  2. 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.
  3. Scrolling up (delta < 0): always shows, unconditionally — regardless of lock state, position, or min-y. An up-scroll is read as "the user wants to see the header again."
  4. Scrolling down past min-y, and not locked: hides.
  5. Locked (#isLocked()): a down-scroll that would otherwise hide is suppressed. Locked = contains focus, has an open descendant, or carries pinned.

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-motion is a pure CSS media query on your side, not a JS branch inside the library.
  • pd:show/pd:hide fire at the moment of the logical state flip, not after any animation settles. This is a deliberate contrast with pd:opened/pd:closed on the disclosure family, which wait for afterAnimations() because those components must apply hidden only once the exit animation finishes. pd-header has 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:

js
const header = document.querySelector('pd-header')
header.pin()      // same as header.pinned = true / setAttribute('pinned', '')
header.unpin()     // same as header.pinned = false

Setting 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):

js
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-within polling, 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 why pd-nav-panel, pd-disclosure, and pd-drawer (all of which set open/data-state="open") are recognized automatically with zero wiring. A hand-rolled dropdown using a different convention won't be seen by this check — mirror data-state="open" on it, or call pin()/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 ​

AttributeTypeDefaultNotes
thresholdnumber (px)8Minimum accumulated scroll delta before a direction change is committed. Non-finite or negative values fall back to the default.
min-ynumber (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.
pinnedboolean, reflectedabsentSee 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 ​

MemberSignatureNotes
pinnedboolean (get/set)Reflects the pinned attribute.
pin()() => voidpinned = true.
unpin()() => voidpinned = 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 ​

EventCancelableWhendetail
pd:shownoVisibility flips to visible (up-scroll, reaching the top, focus entering a hidden header, or pin()/pinned on a hidden header).{ y }
pd:hidenoVisibility 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.

KeyContextBehavior
Tab / Shift+Tabany focusable descendantNative 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 headerEntirely 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-header is an unknown custom element with no implicit ARIA role — add role="banner" directly on it if it represents the page's one main header (omit if it's a repeated/secondary bar, per the banner role'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 needs data-state="open" mirrored onto it (or manual pin()/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).

css
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 ​

html
<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.

Brandpd-header demo — data-state: watch the border color
Section 1 — keep scrolling
Section 2
Section 3 — now scroll back up