Skip to content

Drilldown ​

See it live in the styled storefront › — inside the mobile menu drawer (☰ at a narrow viewport): drill into a category, slide back out.

<pd-drilldown> is a history stack over its <pd-drilldown-panel> children — one active screen at a time, --pd-drill pushes forward, --pd-back pops. It's the coordinator half of the pattern (SPEC layer 2: no state of its own); each panel is a "dumb" leaf that only carries data-state="active"|"inactive" and a label for accessible naming.

html
<pd-drilldown id="dd">
  <pd-drilldown-panel root>
    <ul><li><button commandfor="dd-skincare" command="--pd-drill">Skincare</button></li></ul>
  </pd-drilldown-panel>
  <pd-drilldown-panel id="dd-skincare" label="Skincare">
    <button commandfor="dd" command="--pd-back">← Back</button>
    …
  </pd-drilldown-panel>
</pd-drilldown>

Anatomy ​

html
<pd-drilldown id="dd">
  <!-- 1. `root` marks the panel that starts active; if no panel has it, the
          first panel wins. Keep panels *direct* children — the slide
          choreography grid-stacks them in one shared grid area (SPEC §5.4),
          which only works for siblings. -->
  <pd-drilldown-panel root id="dd-root">
    <ul>
      <li>
        <!-- 2. --pd-drill targets the *destination* panel's id. -->
        <button commandfor="dd-skincare" command="--pd-drill">Skincare</button>
      </li>
    </ul>
  </pd-drilldown-panel>

  <!-- 3. `label` -> role="group" + aria-label, so when focus lands on the
          Back button below (the destination's first tabbable), a screen
          reader announces "Skincare, group" instead of just "Back, button". -->
  <pd-drilldown-panel id="dd-skincare" label="Skincare">
    <!-- 4. --pd-back here targets the *drilldown* (`dd`) — "pop whatever's
            active". Conventionally the panel's first tabbable, so drilling
            in lands focus directly on it. -->
    <button commandfor="dd" command="--pd-back">← Back</button>
    <ul>
      <li><button commandfor="dd-moisturizers" command="--pd-drill">Moisturizers</button></li>
    </ul>
  </pd-drilldown-panel>

  <pd-drilldown-panel id="dd-moisturizers" label="Moisturizers">
    <!-- 5. --pd-back can also target a specific panel's own id — "pop from
            here". Equivalent to targeting `dd` while this panel is active;
            useful when a back button is shared markup and you want it inert
            unless this exact panel is the one currently showing. -->
    <button commandfor="dd-moisturizers" command="--pd-back">← Back</button>
    <a href="/collections/moisturizers">View all</a>
  </pd-drilldown-panel>
</pd-drilldown>

No pd-drilldown-panel children found? pd-drilldown logs one console.warn and stays inert. Panels inserted after connect aren't wired automatically — call refresh() (see Properties & methods).

The stack model ​

The stack lives entirely on <pd-drilldown>. Each --pd-drill pushes a { fromId, invoker } entry — the panel being left, and the exact button that was clicked — so --pd-back can restore both the previous screen and the precise point focus should return to (not just "the panel's first tabbable," though that's the fallback if the stored button was removed in the meantime). Panels themselves are never PdOpenable: no open attribute, no pd:open/pd:close — their data-state/inert/hidden are set directly by the coordinator, and the only event is pd:navigate, fired after the fact and non-cancelable.

Rapid navigation is race-safe: a per-panel activation counter means a pending exit-animation hidden from a superseded deactivate (e.g. drill-then-immediately-back on the same panel) never applies once something else reactivated it. Reactivation removes only inertness the drilldown added, before revealing and focusing the panel; author-supplied inert remains untouched.

Attributes ​

pd-drilldown takes no configuration attributes; it gets an auto-generated id (pd-drilldown-N) if the author didn't provide one, and it manages one piece of presentation state itself:

Managed attributeValuesMeaning
data-directionforward | backThe direction of the most recent navigation, set before the panels change state (absent initially and after reset()). Style hook for directional layer slides — see the recipe below.

pd-drilldown-panel

AttributeTypeDefaultEffect
rootbooleanabsentMarks the panel active on connect. If no panel has it, the first child panel is used.
labelstring (observed)absentSets role="group" + aria-label to the given value, live-updating at runtime. Removing it clears aria-label, and clears role only if the component set it itself — an author-provided role is never clobbered.
idstringauto pd-drilldown-panel-NWhat --pd-drill/--pd-back target.

Properties & methods ​

pd-drilldown

MemberSignatureNotes
refresh()() => voidWires any pd-drilldown-panel appended after connect (panels self-register via the context protocol; there is no MutationObserver — call this after inserting panels dynamically so they get command wiring and initial state). Newly wired, non-active panels become inert and hidden immediately, with no exit animation.
reset()() => voidActivates root and clears the stack. External focus is untouched; focus still inside the outgoing panel is redirected into root so it cannot remain in an inactive screen. Fires pd:navigate with direction: 'reset'. See the reset-on-close recipe below.

pd-drilldown-panel exposes no methods beyond HTMLElement — labeling is attribute-driven only.

Commands ​

CommandValid targetEffect
--pd-drilla pd-drilldown-panel id (the destination)Pushes { fromId: current panel, invoker: the clicked button }, deactivates the current panel, activates the destination, moves focus into it — keyboard-driven drills land on the destination's first tabbable, taps/clicks focus the destination panel itself (Safari would paint a focus ring on any script-focused control) — and fires pd:navigate (direction: 'forward'). No-op if the destination is already active.
--pd-backthe pd-drilldown id ("pop whatever's active") or a pd-drilldown-panel id ("pop from this panel")Pops the top stack entry, reactivates the previous panel, moves focus back into it — keyboard-driven backs return focus to the exact button that drilled in (falls back to the panel if it's gone), taps/clicks focus the reactivated panel itself (Safari would ring the drill button otherwise) — and fires pd:navigate (direction: 'back'). Targeting a panel that isn't the currently active one is silently ignored. No-op on an empty stack.

Events ​

EventCancelableWhendetail
pd:navigatenoafter --pd-drill, --pd-back, or reset() activates a panel{ panelId: string, direction: 'forward' | 'back' | 'reset' }

No pd:open/pd:close/pd:opened/pd:closed — those belong exclusively to PdOpenable elements (pd-disclosure, pd-nav-panel, pd-drawer). Panel activation here is observational only, never cancelable — the drilldown never blocks its own navigation.

Keyboard ​

KeyContextBehavior
Tab / Shift+Tabanywhere in the drilldownOrdinary tab order. Only the active panel's controls are reachable — inactive panels become inert synchronously, then hidden after their exit transition.
Enter / Spaceon a --pd-drill buttonDrills forward: activates the destination, moves focus into it.
Enter / Spaceon a --pd-back buttonPops the stack: reactivates the previous panel, returns focus to the button that opened the current screen.
Escape—Not handled here, by design. A drilldown is normally nested inside a pd-drawer, whose native <dialog> already owns Escape. Wire dismissal at the drawer (or your own container), not per-panel — see SPEC §5.4.

Accessibility ​

Managed by pd-drilldown / pd-drilldown-panel:

  • data-state="active"|"inactive", immediate component-owned inert, and delayed hidden on inactive panels — assistive tech and the tab order only ever see the current screen, including while the outgoing layer is still rendered for animation. Author-supplied inert is preserved.
  • role="group" + aria-label from the label attribute. Why it matters: focus on drill-in moves programmatically straight to a control (conventionally the Back button), not to a heading — without a named group boundary around it, a screen reader user only ever hears "Back, button" and has no idea what section they landed in. label is what turns that into "Skincare, group — Back, button" (WCAG 4.1.2 Name, Role, Value in spirit: the destination's identity is exposed, not just the focused control's).
  • Back-button visibility is resynced on every activation — hidden while the stack is empty, so the root screen never shows a dead-end control, and a fresh drill always reveals it correctly regardless of prior navigation.
  • No aria-controls — commandfor is already the programmatic association, consistent library-wide.
  • Focus management in both directions (see the keyboard table) — predictable, WCAG 2.4.3-aligned focus order across a navigation change instead of focus getting lost on a hidden element.

Author must provide:

  • label on every non-root panel (strongly recommended) — without it, drilling in is functionally silent context-wise for screen reader users.
  • Semantic content inside each panel (lists, links, headings) — panels are unstyled containers.
  • Escape/dismiss handling — belongs to the wrapping pd-drawer (or your own listener if the drilldown is used standalone, outside a drawer).
  • Visual focus styles — the component sets no CSS.

Live demo ​

Styling: Vanilla CSS — grid-stacked panels ​

All panels share the same grid cell (grid-area: 1 / 1) instead of being laid out in flow. Because hidden is only applied after the exit animation settles (SPEC §3), so the outgoing and incoming panel are both rendered — and both occupying that same cell — for the whole transition, which is what produces the slide-past-each-other effect. The outgoing panel becomes inert immediately, so only the incoming screen remains interactive. The animation itself is still pure CSS.

css
/* 1. The drilldown is the grid container; panels are the stacked children. */
pd-drilldown {
  display: grid;
  overflow: hidden;
  position: relative;
}

pd-drilldown-panel {
  grid-area: 1 / 1;
  display: grid;
  align-content: start;
  gap: 0.75rem;
  padding: 1rem;
  transition: transform 220ms ease;
}

/* 2. Default direction: incoming panels enter from the right, panels being
      left exit to the left. This is direction-agnostic on purpose — see the
      optional enhancement below for correct reversal on --pd-back. */
pd-drilldown-panel[data-state='active'] {
  transform: translateX(0);
}
pd-drilldown-panel[data-state='inactive'] {
  transform: translateX(-100%);
}

/* 3. Entrance transition for a freshly activated panel (needs a "before"
      frame to animate from — see the drawer page for the same technique
      applied to a dialog + ::backdrop). Scoped under [data-direction] so the
      very first reveal (e.g. a containing drawer opening, before any
      navigation happened) doesn't replay a slide. */
@starting-style {
  pd-drilldown[data-direction] pd-drilldown-panel[data-state='active'] {
    transform: translateX(100%);
  }
}

/* 4. Respect reduced motion. */
@media (prefers-reduced-motion: reduce) {
  pd-drilldown-panel {
    transition: none;
  }
}

Correct the slide direction on the way back — no JS needed. The rules above always exit left/enter from the right, which reads correctly for forward navigation but backward on --pd-back. The component maintains data-direction="forward" | "back" on pd-drilldown for exactly this; flip both sides of the back case in CSS:

css
/* Outgoing layer returns to the right on back… */
pd-drilldown[data-direction='back'] pd-drilldown-panel[data-state='inactive'] {
  transform: translateX(100%);
}
/* …and the incoming layer's first frame comes from the left. */
@starting-style {
  pd-drilldown[data-direction='back'] pd-drilldown-panel[data-state='active'] {
    transform: translateX(-100%);
  }
}

Don't mirror pd:navigate onto an attribute yourself

It looks equivalent, but isn't: the component moves focus into the destination panel beforepd:navigate fires, and that focus move forces a style flush. A listener-set attribute arrives after that flush, so the incoming panel's @starting-style is evaluated against the previous direction — forward slides don't play at all and back slides start from the wrong side. This is why data-direction is set by the component before any panel changes state (SPEC §5.4).

Styling: Tailwind ​

[grid-area:1/1] is an arbitrary-property utility placing every panel in the same cell — the Tailwind equivalent of the vanilla recipe above, no nested flex required.

html
<pd-drilldown id="dd" class="relative grid overflow-hidden rounded-lg border">
  <pd-drilldown-panel
    root
    id="dd-root"
    class="
      [grid-area:1/1] grid content-start gap-3 p-4
      transition-transform duration-200 ease-out
      data-[state=inactive]:-translate-x-full
      motion-reduce:transition-none
    "
  >
    …
  </pd-drilldown-panel>
  <pd-drilldown-panel
    id="dd-skincare"
    label="Skincare"
    class="
      [grid-area:1/1] grid content-start gap-3 p-4
      transition-transform duration-200 ease-out
      data-[state=inactive]:-translate-x-full
      motion-reduce:transition-none
    "
  >
    …
  </pd-drilldown-panel>
</pd-drilldown>

Recipes ​

Mobile menu: drawer + drilldown composed ​

The canonical composition (SPEC §1.1): pd-drawer > dialog > pd-drilldown. The drawer supplies the modal surface, scroll lock, and Escape-to-close; the drilldown supplies the multi-level navigation inside it. This much is plain HTML — no JS required:

html
<button commandfor="mobile-menu" command="show-modal">☰ Menu</button>

<pd-drawer>
  <dialog id="mobile-menu" aria-label="Menu">
    <button commandfor="mobile-menu" command="close" aria-label="Close menu">✕</button>

    <pd-drilldown id="mobile-menu-nav">
      <pd-drilldown-panel root id="mm-root">
        <ul>
          <li><button commandfor="mm-skincare" command="--pd-drill">Skincare</button></li>
          <li><a href="/pages/about">About</a></li>
        </ul>
      </pd-drilldown-panel>

      <pd-drilldown-panel id="mm-skincare" label="Skincare">
        <button commandfor="mobile-menu-nav" command="--pd-back">← Back</button>
        <ul>
          <li><a href="/collections/cleansers">Cleansers</a></li>
          <li><a href="/collections/moisturizers">Moisturizers</a></li>
        </ul>
      </pd-drilldown-panel>
    </pd-drilldown>
  </dialog>
</pd-drawer>

Style the drawer's <dialog> per the drawer page's recipes and the drilldown panels per the grid-stacked recipe above — the two compose without any additional wrapper markup, matching the flat-markup rule (SPEC §1.2).

Reset the menu when the drawer closes ​

reset() leaves external focus alone and fires pd:navigate, but nothing calls it automatically — the mobile-menu-nav drilldown above will still be showing whatever screen the user last drilled into the next time the drawer reopens, unless you reset it yourself. Wire it to the drawer's pd:closed, which fires once the close animation has fully settled — not on pd:close, which fires before the exit animation even starts and could yank the drilldown back to root while it's still visibly sliding shut:

js
const drawer = document.querySelector('pd-drawer')
const nav = document.getElementById('mobile-menu-nav')
drawer.addEventListener('pd:closed', (event) => {
  if (event.target === drawer) nav.reset()
})

The target check matters when the drilldown contains disclosures: pd:* events bubble, so an accordion panel finishing its own close also reaches the drawer listener.