Skip to content

Nav & mega menu — pd-nav + pd-nav-panel ​

See it live in the styled storefront › — the mega menu in the demo shop's header: hover intent, single-open, and the full keyboard map.

pd-nav is a coordinator: it owns no state of its own and instead orchestrates one or more pd-nav-panel descendants — the disclosure panels that make up a mega menu. pd-nav-panel owns exactly one piece of state (open) and behaves like pd-disclosure plus nav-specific coordination (single-open, hover intent, focus handling, arrow keys).

Together they implement the APG Disclosure Navigation Menu pattern, not a menu/menubar widget. That distinction drives most of the design decisions below.

Anatomy ​

html
<nav aria-label="Main">                                          <!-- 1 -->
  <pd-nav hover open-on-focus>                                    <!-- 2 -->
    <ul>                                                          <!-- 3 -->
      <li>
        <a href="/collections/skincare" data-pd-hover-for="mm-skincare">Skincare</a> <!-- 4 -->
        <button commandfor="mm-skincare" command="--pd-toggle" aria-label="Skincare menu">▾</button> <!-- 5 -->
        <pd-nav-panel id="mm-skincare">                          <!-- 6 -->
          <a href="/skincare/serums">Serums</a>
          <a href="/skincare/masks">Masks</a>
        </pd-nav-panel>
      </li>
      <li><a href="/pages/about">About</a></li>                  <!-- 7 -->
    </ul>
  </pd-nav>
</nav>
  1. <nav aria-label> is author-provided. pd-nav never adds landmark semantics or a label — it doesn't know how many navs are on the page or what to call them.
  2. hover and open-on-focus are both opt-in (§ below). Neither is required for a WCAG-passing menu.
  3. Flat semantic markup: a plain <ul>/<li> list. Associations resolve through commandfor/data-pd-hover-for, but native Tab order still follows source order—put each panel immediately after its owning button inside the same <li> so Tab and Shift+Tab cross that boundary predictably.
  4. The visible nav link. data-pd-hover-for="mm-skincare" folds this link into panel mm-skincare's hover/focus region without making it an invoker — clicking it navigates normally.
  5. The keyboard-required invoker. A button[commandfor] targeting the panel is what makes the panel reachable without a mouse; it needs its own accessible name since "▾" carries none.
  6. The panel itself — no trigger/panel wrapper. It behaves exactly like pd-disclosure.
  7. A plain link with no panel is just... a link. Not every top-level stop needs a mega panel.

Why not role="menu" / aria-haspopup? ​

The ARIA Authoring Practices Guide's menu/menubar pattern (role="menu", role="menuitem", aria-haspopup, roving tabindex, arrow-key-only navigation, typeahead, close-on-activate) is built for action menus — File/Edit-style command lists where activating an item runs a command and the menu is dismissed. It is explicitly not the pattern for site navigation: nav items are links, users expect standard link behavior (Ctrl/Cmd-click to open in a new tab, visited-state styling, browser back button, screen readers announcing "link" not "menu item"), and a mega panel under a nav is one disclosure among several ordinary page links, not an isolated modal-like widget.

Applying role="menu" to a mega menu also makes an accessibility promise the implementation doesn't keep: AT users are told to expect roving-tabindex arrow navigation and typeahead, and get plain Tab order instead — a worse experience than no ARIA at all. aria-haspopup has the same problem: it declares a popup widget (menu, listbox, tree, grid, dialog), not a disclosure region.

pd-nav/pd-nav-panel therefore use the APG Disclosure Navigation Menu pattern instead: an ordinary button with aria-expanded toggling an ordinary panel of ordinary links. Nothing here is a menu; everything keeps its native semantics, and aria-expanded is the only piece of custom ARIA state involved (managed automatically — see Accessibility).

Attributes ​

AttributeElementTypeDefaultNotes
hoverpd-navbooleanoffOpt in to hover-intent opening (§ below).
hover-open-delaypd-navnumber (ms)100Debounce before a hovered panel opens.
hover-close-delaypd-navnumber (ms)200Grace period before a panel closes on pointer-out.
open-on-focuspd-navbooleanoffOpt in to opening a panel when its invoker/hover-for element receives visible keyboard focus.
close-on-focusoutpd-nav"false" to disableenabledCloses when focus leaves the nav or enters a different top-level/panel region. Any value other than the literal string "false" keeps it enabled.
arrow-navpd-nav"false" to disableenabledTurns off the whole arrow-key enhancement; Tab/Enter/Space still work.
orientationpd-nav"vertical" | default horizontalhorizontalSwaps which axis walks top-level stops vs. opens/closes a panel.
idpd-nav-panelstringauto-generated (pd-nav-panel-N)Give panels a stable, human-readable id — it's the commandfor/data-pd-hover-for target.
openpd-nav-panelboolean, reflectedabsent (closed)Logical state (SPEC §3). Server-renderable.

Properties & methods ​

MemberElementSignatureNotes
openpd-nav-panelboolean (get/set)Setting it bypasses pd:open/pd:close cancelation — reason is 'attribute'.
show()pd-nav-panel(reason?: Reason) => booleanCancelable open; returns false if a pd:open listener called preventDefault().
hide()pd-nav-panel(reason?: Reason) => booleanCancelable close.
toggle()pd-nav-panel(force?: boolean, reason?: Reason) => boolean

pd-nav itself exposes no public state API — it has none to expose. Everything it does is derived live from its descendants (open panels, invokers, hover-for elements) each time it's needed.

Commands ​

CommandValid targetEffect
--pd-togglepd-nav-panelToggle open/closed.
--pd-openpd-nav-panelOpen (no-op if already open).
--pd-closepd-nav-panelClose (no-op if already closed).

pd-nav is never a commandfor target — it has no open/closed state of its own to command.

Events ​

All events are dispatched from pd-nav-panel (bubbles: true, composed: true), so a listener on pd-nav or the containing <nav> catches everything.

EventCancelableWhendetail
pd:openyesBefore a panel opens.{ reason }
pd:closeyesBefore a panel closes.{ reason }
pd:openednoAfter open + data-state="open" are applied.{ reason }
pd:closednoAfter exit animations settle and hidden is applied.{ reason }

reason is one of 'command' | 'hover' | 'focus' | 'keyboard' | 'outside' | 'escape' | 'focusout' | 'api' | 'attribute' — every close path in this component (single-open handoff, outside click, focusout, Escape, hover timeout) fills in the reason that actually caused it, so a listener can tell "user pressed Escape" apart from "another panel took over."

Keyboard ​

Available controls keep native DOM order — there is no roving tabindex. Controls inside closed/closing panels are excluded by inert; the table below is an enhancement layered on top of default Tab/Enter/Space browser behavior.

KeyContextBehavior
Escapeanywhere in the document (including inside a text field)Close the innermost open panel and consume the key; focus its primary invoker only when focus was inside the nav — a hover-opened panel dismissed with focus elsewhere closes without moving focus.
ArrowRight / ArrowLeftfocus on a top-level stopMove to the next/previous top-level stop. No wrap.
Home / Endfocus on a top-level stopJump to the first/last top-level stop.
ArrowDownfocus on an invoker or data-pd-hover-for elementOpen its panel, focus the panel's first tabbable element.
ArrowUpsame, panel openClose the panel.
ArrowDown / ArrowUpfocus inside an open panelMove to the next/previous tabbable element in the panel. No wrap.

Notes:

  • Top-level stops = every tabbable a[href]/button owned by this nav that is not inside a pd-nav-panel (i.e. the visible menu bar), in live DOM order. Hidden, inert, disabled, and tabindex="-1" elements are skipped.
  • orientation="vertical" swaps the axes: ArrowDown/ArrowUp walk top-level stops, ArrowRight/ArrowLeft open/close a panel — matching a vertical sidebar nav's expected feel.
  • The primary invoker of a panel is the first enabled, tabbable open/toggle button[commandfor] targeting it that is not physically inside the panel. Hidden/inert, programmatic-only, disabled, and close-only buttons are skipped, so Escape always returns to a usable entry point. This rule is specific to pd-nav: pd-drawer restores the exact command source (or pre-API-open active element), and pd-disclosure never moves focus at all.
  • Arrow handling is fully suppressed while focus is in input, textarea, select, or [contenteditable] — predictive-search fields live inside panels and must keep native text-editing key behavior. Escape is exempt from this guard; it must always be able to dismiss.
  • A handled Escape is default-prevented even if a pd:close listener vetoes the close. In nested navs or a nav inside a native dialog, one key dismisses only the innermost layer; press Escape again to dismiss the next layer.

Hover intent (hover) and WCAG 1.4.13 ​

hover is opt-in because hover-opening is a convenience, not a requirement — the panel is already fully operable by keyboard/click via its button. When enabled, pd-nav delegates pointerover on itself for entry (membership resolved with closest()) and listens for pointerleave on its own root for exit — leaving the root always means leaving the whole region — restricted to pointerType === 'mouse' — touch and pen never trigger it. This matters because touch has no persistent hover state; treating a touchstart-flavored pointerover as "hover" would either open panels the user never asked for, or trap them (no way to "un-hover" on a touchscreen). Touch users get the panel exactly the same way keyboard users do: tap the button.

The hover region of panel X is the union of: X's invoker button(s), any element carrying data-pd-hover-for="X", and X itself. Pointer movement anywhere in that region keeps the panel open; leaving it starts a close countdown. Two debounces shape the feel:

  • hover-open-delay (default 100ms) — prevents every panel along the bar flashing open as the pointer merely passes over the nav on its way somewhere else.
  • hover-close-delay (default 200ms) — a grace period for the pointer to travel from the invoker down into the panel below it (there is a visual gap; a real mouse trajectory is not a straight line). Re-entering the region before the timer fires cancels the pending close.

Hovering a second trigger while one panel is open hands off directly: the new panel's open-timer starts and the old panel closes (single-open coordination, same as clicking).

This design is what satisfies WCAG 2.2 SC 1.4.13 (Content on Hover or Focus), whose three requirements map directly onto the implementation:

SC 1.4.13 requirementHow pd-nav satisfies it
Dismissible — a way to dismiss the extra content without moving pointer or focusEscape closes the open panel from anywhere in the document — the listener is document-scoped precisely so a hover-opened panel can be dismissed while focus sits outside the nav, without focus theft.
Hoverable — the pointer can move onto the additional content without it disappearingThe hover region includes the panel itself, not just its trigger, and pointerleave is measured against the whole pd-nav subtree, not per-element boundaries.
Persistent — the content stays visible until the user dismisses it, not on a fixed timeouthover-close-delay is a debounce against pointer travel, not an auto-dismiss timer—the panel never closes while the pointer stays in its region or keyboard focus remains in the associated link/button/panel region.

Without the hover attribute, none of this runs; the panel opens only via click/tap (--pd-toggle) or the keyboard enhancement above — which is already 1.4.13-exempt because nothing appears "on hover or focus" in the first place.

Open-on-focus (open-on-focus) ​

With open-on-focus, Tab-ing onto an invoker button or a data-pd-hover-for element opens its panel automatically (reason 'focus'), gated by a :focus-visible check so a mouse click that also happens to focus the button doesn't double-open it (the click already opened it via the command path). Re-focusing something already inside the same open panel never re-triggers. Regardless of this opt-in, an explicitly opened panel remains open throughout its own associated link/button/panel region and closes when focus enters another region (reason 'focusout'), unless close-on-focusout="false" opts out.

Trade-off to understand before enabling it: it means simply Tab-ing through the nav bar opens every mega panel along the way as a side effect of reaching later items — a keyboard user tabbing past "Skincare" to reach "About" will see the Skincare panel flash open. That's the deliberate cost of not requiring a dedicated key press to preview a panel's contents while tabbing. If that trade-off doesn't suit your nav (e.g. panels are wide/tall and the flash is disorienting), leave the attribute off — the panel is still fully reachable via ArrowDown on the invoker, or by pressing Enter/Space on the button itself. open-on-focus is sugar, not a baseline accessibility requirement.

One thing it does not change: the dev-time console warning that fires when a panel has no button[commandfor] invoker (see pd-nav-panel's "unreachable panel" check) fires regardless of whether open-on-focus is set, even though a focusable data-pd-hover-for link technically becomes keyboard-reachable when the attribute is on. Always ship a real button invoker — don't rely on open-on-focus plus a link as your only path to a panel.

data-pd-hover-for — hover region without a second invoker ​

The invoker button and the "trigger" a user actually hovers/focuses don't have to be the same element. data-pd-hover-for="mm-skincare" on the visible nav link means: this link is part of panel mm-skincare's hover region and, if open-on-focus is set, its focus region too — without turning the link into an aria-expanded toggle (it stays a normal <a href>; ARIA state is only ever written to real commandfor invokers). It also participates in the keyboard map: pressing ArrowDown while focused on the hover-for link opens the panel exactly like pressing it on the button does.

Resolution order (#resolveAssociation) is: closest commandfor invoker → closest data-pd-hover-for element → the panel the pointer/focus is physically inside (so hovering a link inside an already-open panel doesn't require it to carry data-pd-hover-for itself — containment is enough).

Accessibility ​

Managed automatically:

  • aria-expanded synced on every button[commandfor] invoker of a panel, flipped at the same moment the logical state changes (not after the exit animation). Non-button hover-for elements (e.g. the nav link) never receive it — a link isn't a disclosure trigger.
  • Component-owned inert applied synchronously when a panel closes, then removed before it opens. This keeps a still-rendered exit animation out of the accessibility tree and Tab order; author-supplied inertness is never removed.
  • No aria-controls is ever written. commandfor already provides the programmatic button↔panel relationship; a parallel aria-controls would be redundant and harder to keep in sync — the test suite asserts it's absent.
  • No role="menu"/"menubar"/"menuitem", no aria-haspopup — see the rationale above.
  • A dev-only console.warn when a pd-nav-panel inside a pd-nav has no enabled, tabbable --pd-toggle/--pd-open button outside the panel ("cannot be opened by keyboard (WCAG 2.1.1)"). Disabled, hidden/inert, tabindex="-1", missing-command, and close-only buttons do not make a closed panel reachable. For nested navs, hidden/inert ancestors outside the nav are ignored because opening the ancestor panel reveals the complete inner interaction. It's silent for panels outside any pd-nav.
  • Escape returns focus deterministically to the panel's primary invoker (WCAG 2.4.3 — focus never gets orphaned on a now-hidden element).

You must provide:

  • The <nav aria-label="…"> landmark wrapper. pd-nav asserts nothing about page structure.
  • An accessible name on icon-only invokers (aria-label="Skincare menu" on a "▾" button) — the component syncs aria-expanded on whatever invoker exists, it doesn't invent a label for it.
  • Heading structure inside a panel's columns if it has more than one group of links — panel content is opaque to the component.
  • A real button[commandfor] invoker for every panel, always (see the open-on-focus note above).
  • Visual affordance for the open/closed state (data-state="open"|"closed" is the hook; styling is entirely yours).

Styling — vanilla CSS ​

Grid-first per the library's layout rule: the top-level bar is a genuine one-dimensional run (flex would be equally valid there), but the mega panel's column layout is inherently two-dimensional and uses grid.

css
/* Functional base (ships as styles/base.css — include or replicate) */
[hidden] { display: none !important; }
pd-nav, pd-nav-panel { display: block; }

/* Top-level bar: a one-dimensional run of stops */
pd-nav > ul {
  display: grid;
  grid-auto-flow: column;
  justify-content: start;
  align-items: center;
  gap: 1.5rem;
  list-style: none;
  margin: 0;
  padding: 0;
}

pd-nav li {
  position: relative; /* anchors the panel below this stop */
  display: grid;
  grid-auto-flow: column;
  align-items: center;
  gap: 0.25rem;
}

/* Chevron rotates with the state it announces (aria-expanded), not a class */
pd-nav button[commandfor] {
  transition: transform 150ms ease-out;
}
pd-nav button[commandfor][aria-expanded='true'] {
  transform: rotate(180deg);
}

/* The mega panel: 2D grid of link columns */
pd-nav-panel {
  position: absolute;
  inset-inline-start: 0;
  top: 100%;
  z-index: 20;
  display: grid;
  grid-template-columns: repeat(3, minmax(10rem, 1fr));
  gap: 1.5rem 2rem;
  min-width: 32rem;
  padding: 1.5rem;
  background: canvas;
  border: 1px solid color-mix(in oklab, canvasText 15%, transparent);
}

/* Exit animation: data-state + inert flip immediately; `hidden` waits */
pd-nav-panel[data-state='open'] {
  animation: pd-nav-panel-in 160ms ease-out;
}
pd-nav-panel[data-state='closed'] {
  animation: pd-nav-panel-out 160ms ease-in forwards;
}

@keyframes pd-nav-panel-in {
  from { opacity: 0; transform: translateY(-4px); }
  to   { opacity: 1; transform: translateY(0); }
}
@keyframes pd-nav-panel-out {
  from { opacity: 1; }
  to   { opacity: 0; }
}

/* The initial closed state on page load is also `[hidden]` in the same tick
   (no animation wait on first paint) — CSS animations don't run on
   display:none elements, so this rule never flashes on load; it only plays
   on a real, user-triggered close, while `[hidden]` is not yet applied.
   The component-owned `inert` attribute already prevents interaction. */
@media (prefers-reduced-motion: reduce) {
  pd-nav-panel,
  pd-nav button[commandfor] {
    animation: none !important;
    transition: none !important;
  }
}

Styling — Tailwind ​

html
<nav aria-label="Main">
  <pd-nav hover open-on-focus>
    <ul class="grid auto-cols-max grid-flow-col items-center gap-6 list-none m-0 p-0">
      <li class="relative grid grid-flow-col items-center gap-1">
        <a href="/collections/skincare" data-pd-hover-for="mm-skincare" class="py-2">Skincare</a>
        <button
          commandfor="mm-skincare"
          command="--pd-toggle"
          aria-label="Skincare menu"
          class="transition-transform duration-150 ease-out aria-expanded:rotate-180 motion-reduce:transition-none"
        >▾</button>
        <pd-nav-panel
          id="mm-skincare"
          class="absolute inset-x-0 top-full z-20 grid grid-cols-3 gap-x-8 gap-y-6 min-w-[32rem] p-6 bg-white border border-gray-200
                 data-[state=open]:[animation:pd-nav-panel-in_160ms_ease-out]
                 data-[state=closed]:[animation:pd-nav-panel-out_160ms_ease-in_forwards]
                 motion-reduce:[animation:none]"
        >
          <a href="/skincare/serums">Serums</a>
          <a href="/skincare/masks">Masks</a>
        </pd-nav-panel>
      </li>
      <li><a href="/pages/about" class="py-2">About</a></li>
    </ul>
  </pd-nav>
</nav>
css
/* Tailwind has no utility for *defining* a keyframe — declare it once in your
   CSS entry (e.g. via @utility or a plain @keyframes block) and reference it
   through the arbitrary-value classes above. motion-reduce: is a built-in
   Tailwind variant, no extra config needed. */
@keyframes pd-nav-panel-in {
  from { opacity: 0; transform: translateY(-4px); }
  to   { opacity: 1; transform: translateY(0); }
}
@keyframes pd-nav-panel-out {
  from { opacity: 1; }
  to   { opacity: 0; }
}

aria-expanded:rotate-180 is a built-in Tailwind ARIA variant — it targets the same element the aria-expanded attribute lives on, so it's applied directly to the invoker button rather than routed through a group. For styling a different sibling based on a panel's data-state (e.g. tinting the whole <li> while its panel is open), Tailwind v4's has-* variant reaches sideways without an extra wrapper: has-[[data-state=open]]:bg-gray-50 on the <li>.

Live demo ​

Hover the "Skincare" link/chevron (mouse only), click the chevron, or Tab to it — all three open the panel. Escape closes it and returns focus to the chevron button. ArrowRight/ArrowLeft move between "Skincare" and "About"; ArrowDown on the chevron jumps into the panel's columns.