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
<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><nav aria-label>is author-provided.pd-navnever adds landmark semantics or a label — it doesn't know how many navs are on the page or what to call them.hoverandopen-on-focusare both opt-in (§ below). Neither is required for a WCAG-passing menu.- Flat semantic markup: a plain
<ul>/<li>list. Associations resolve throughcommandfor/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. - The visible nav link.
data-pd-hover-for="mm-skincare"folds this link into panelmm-skincare's hover/focus region without making it an invoker — clicking it navigates normally. - 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. - The panel itself — no trigger/panel wrapper. It behaves exactly like
pd-disclosure. - 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
| Attribute | Element | Type | Default | Notes |
|---|---|---|---|---|
hover | pd-nav | boolean | off | Opt in to hover-intent opening (§ below). |
hover-open-delay | pd-nav | number (ms) | 100 | Debounce before a hovered panel opens. |
hover-close-delay | pd-nav | number (ms) | 200 | Grace period before a panel closes on pointer-out. |
open-on-focus | pd-nav | boolean | off | Opt in to opening a panel when its invoker/hover-for element receives visible keyboard focus. |
close-on-focusout | pd-nav | "false" to disable | enabled | Closes 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-nav | pd-nav | "false" to disable | enabled | Turns off the whole arrow-key enhancement; Tab/Enter/Space still work. |
orientation | pd-nav | "vertical" | default horizontal | horizontal | Swaps which axis walks top-level stops vs. opens/closes a panel. |
id | pd-nav-panel | string | auto-generated (pd-nav-panel-N) | Give panels a stable, human-readable id — it's the commandfor/data-pd-hover-for target. |
open | pd-nav-panel | boolean, reflected | absent (closed) | Logical state (SPEC §3). Server-renderable. |
Properties & methods
| Member | Element | Signature | Notes |
|---|---|---|---|
open | pd-nav-panel | boolean (get/set) | Setting it bypasses pd:open/pd:close cancelation — reason is 'attribute'. |
show() | pd-nav-panel | (reason?: Reason) => boolean | Cancelable open; returns false if a pd:open listener called preventDefault(). |
hide() | pd-nav-panel | (reason?: Reason) => boolean | Cancelable 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
| Command | Valid target | Effect |
|---|---|---|
--pd-toggle | pd-nav-panel | Toggle open/closed. |
--pd-open | pd-nav-panel | Open (no-op if already open). |
--pd-close | pd-nav-panel | Close (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.
| Event | Cancelable | When | detail |
|---|---|---|---|
pd:open | yes | Before a panel opens. | { reason } |
pd:close | yes | Before a panel closes. | { reason } |
pd:opened | no | After open + data-state="open" are applied. | { reason } |
pd:closed | no | After 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.
| Key | Context | Behavior |
|---|---|---|
Escape | anywhere 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 / ArrowLeft | focus on a top-level stop | Move to the next/previous top-level stop. No wrap. |
Home / End | focus on a top-level stop | Jump to the first/last top-level stop. |
ArrowDown | focus on an invoker or data-pd-hover-for element | Open its panel, focus the panel's first tabbable element. |
ArrowUp | same, panel open | Close the panel. |
ArrowDown / ArrowUp | focus inside an open panel | Move to the next/previous tabbable element in the panel. No wrap. |
Notes:
- Top-level stops = every tabbable
a[href]/buttonowned by this nav that is not inside apd-nav-panel(i.e. the visible menu bar), in live DOM order. Hidden, inert, disabled, andtabindex="-1"elements are skipped. orientation="vertical"swaps the axes:ArrowDown/ArrowUpwalk top-level stops,ArrowRight/ArrowLeftopen/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 topd-nav:pd-drawerrestores the exact command source (or pre-API-open active element), andpd-disclosurenever 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.Escapeis exempt from this guard; it must always be able to dismiss. - A handled
Escapeis default-prevented even if apd:closelistener 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(default100ms) — prevents every panel along the bar flashing open as the pointer merely passes over the nav on its way somewhere else.hover-close-delay(default200ms) — 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 requirement | How pd-nav satisfies it |
|---|---|
| Dismissible — a way to dismiss the extra content without moving pointer or focus | Escape 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 disappearing | The 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 timeout | hover-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-expandedsynced on everybutton[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
inertapplied 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-controlsis ever written.commandforalready provides the programmatic button↔panel relationship; a parallelaria-controlswould be redundant and harder to keep in sync — the test suite asserts it's absent. - No
role="menu"/"menubar"/"menuitem", noaria-haspopup— see the rationale above. - A dev-only
console.warnwhen apd-nav-panelinside apd-navhas no enabled, tabbable--pd-toggle/--pd-openbutton 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 anypd-nav. Escapereturns 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-navasserts nothing about page structure. - An accessible name on icon-only invokers (
aria-label="Skincare menu"on a "▾" button) — the component syncsaria-expandedon 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 theopen-on-focusnote 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.
/* 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
<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>/* 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.