Skip to content

pd-disclosure ​

See it live in the accordion example › — grouped disclosures in a client's theme styling; the Accordion page covers the grouping layer.

A generic show/hide panel (SPEC §5.1). It underpins every other panel in the library — pd-nav-panel and pd-drawer's open/close pipeline are the same state machine — but on its own it's the plain building block for FAQ answers, "Shipping & returns" blurbs, or any single collapsible region.

The defining decision: the element is the panel. There is no separate trigger/panel wrapper pair to keep in sync — you write a <button commandfor> anywhere in the document and a <pd-disclosure> anywhere else, and the id/commandfor relationship is the only link between them.

Anatomy ​

html
<!-- The invoker: any <button>, anywhere in the document. commandfor points at
     the panel's id; command selects which half of the open/close pipeline. -->
<button commandfor="shipping" command="--pd-toggle">
  Shipping &amp; returns
</button>

<!-- The panel. No wrapper — this element IS what opens and closes.
     id is required for commandfor to resolve; omit it and pd-disclosure
     generates one (pd-disclosure-N) so the button relationship still works. -->
<pd-disclosure id="shipping">
  <p>Free shipping on orders over $50. <a href="/returns">Returns policy</a>.</p>
</pd-disclosure>
  • The button can be a sibling, an ancestor's other child, anywhere — commandfor is a global id reference, not a DOM-position requirement.
  • Author open on <pd-disclosure> for server-rendered "starts open" panels; no flash, no JS needed for the initial state.
  • Wrap the button in a heading (<h3>) when the disclosure is one item in an accordion/FAQ list, per the APG Disclosure pattern — pd-disclosure has no opinion on heading structure, that's yours to add.

Accordion (grouped, exclusive) ​

html
<h3><button commandfor="faq-1" command="--pd-toggle">Do you ship internationally?</button></h3>
<pd-disclosure id="faq-1" group="faq" open>…</pd-disclosure>

<h3><button commandfor="faq-2" command="--pd-toggle">What's the returns window?</button></h3>
<pd-disclosure id="faq-2" group="faq">…</pd-disclosure>

group="faq" is opt-in: without it, disclosures are fully independent and any number can be open at once. With it, showing one pd-disclosure closes every other connected (same document/root) disclosure sharing that group name — the closes go through the normal cancelable hide('api') path, so a pd:close listener on a sibling can still veto its own closing.

Attributes ​

AttributeTypeDefaultNotes
openbooleanabsent (closed)Logical state, source of truth. Server-renderable. Reflects the open property; setting/removing it directly bypasses pd:open/pd:close cancelation (reason: 'attribute').
groupstringnoneAccordion exclusivity key. Opening this disclosure closes every other pd-disclosure in the same root with the same group value.
idstringauto-generatedOnly filled in when missing (pd-disclosure-N). Set your own when you need a stable, human-readable target for commandfor.

Properties & methods ​

MemberSignatureNotes
openboolean (get/set)Get: hasAttribute('open'). Set: reflects the attribute — same cancelation-bypassing behavior as author markup.
show(reason?)(reason?: Reason) => booleanCancelable open. Returns false if a pd:open listener called preventDefault(); no-op (returns true) if already open.
hide(reason?)(reason?: Reason) => booleanCancelable close. Returns false if pd:close was prevented; no-op if already closed.
toggle(force?, reason?)(force?: boolean, reason?: Reason) => booleanforce omitted flips current state; force: true/false pins it (still goes through show/hide, still cancelable).

reason defaults to 'api' for all three methods but accepts any value from the shared Reason union ('command' | 'hover' | 'focus' | 'keyboard' | 'outside' | 'escape' | 'focusout' | 'api' | 'attribute') so you can tag programmatic calls to match how your own code triggered them.

Commands ​

CommandValid targetEffect
--pd-togglepd-disclosureFlips open ↔ closed.
--pd-openpd-disclosureOpens; no-op if already open (one-way — a second click does nothing).
--pd-closepd-disclosureCloses; no-op if already closed (one-way).

All three route through show()/hide()/toggle() with reason: 'command'. (They don't call preventDefault() on the command event — a custom --pd-* command has no default action to suppress. Only pd-drawer's interception of the native show-modal/close commands does.)

Events ​

EventCancelableWhendetail
pd:openyesBefore opening (from show(), including via a command).{ reason }
pd:closeyesBefore closing (from hide()).{ reason }
pd:openednoRight after the open attribute and data-state="open" are applied — immediate, no animation wait.{ reason }
pd:closednoAfter exit animations on the element finish (getAnimations({subtree:true}) settle) and hidden is applied.{ reason }

All events bubble and are composed ({ bubbles: true, composed: true }), so a listener on an ancestor or the document catches them without wiring anything per-instance. Direct open/removeAttribute('open') mutation skips pd:open/pd:close entirely (per §4 the attribute is the source of truth) but still fires pd:opened/pd:closed — cancelation is what's skipped, not the "did-happen" notification.

Keyboard ​

pd-disclosure adds no keyboard handling of its own — the interactive surface is a plain <button>, so keyboard operability is free from the platform:

KeyContextBehavior
Tab / Shift+TabanywhereMoves focus to/from the invoker button in normal document order (native).
Enter / Spaceinvoker button focusedActivates the button (native), which dispatches the command event that pd-disclosure handles.

There is no Escape-to-close. That's deliberate: pd-disclosure is not a modal or an overlay, so nothing needs a dismiss shortcut on top of the button that opened it. (pd-nav and pd-drawer add Escape handling at their own layer, for their own overlay semantics.) Focus never moves when a disclosure opens or closes — the button that was clicked keeps focus, which is correct here: unlike a drilldown or modal, nothing new needs to become the user's context.

Accessibility ​

The component manages:

  • aria-expanded on every button[commandfor="<id>"] invoker, synced to true/false at the moment the logical state flips — immediately, not deferred until the exit animation finishes. Multiple invokers targeting the same disclosure (e.g. a "read more" link duplicated at the top and bottom of a long page) all stay in sync.
  • Component-owned inert on the panel synchronously when it closes, so exit-animation content is immediately absent from the accessibility tree and Tab order. hidden follows after the exit animation settles (or immediately on a closed first paint). Opening removes only inertness the component added; an author-supplied inert attribute is preserved.
  • data-state="open"|"closed" for styling hooks, always present after connect.
  • The panel's id, generated only when missing, so commandfor always has something to resolve to even if you forget to set one.

The component never sets aria-controls. commandfor already creates the programmatic button→target relationship the Invoker Commands API defines, and duplicating it as aria-controls would be redundant (and every pd-* component in this library follows the same no-aria-controls rule — see SPEC §2.3). This is asserted in the unit tests, not just a convention.

You must provide:

  • A real <button> as the invoker — never a styled <div>/<a role="button">. Only a native button gets keyboard operability, focus styles, and aria-expanded support for free.
  • An accessible name on the button that says what will appear ("Shipping & returns", not "Toggle" or "▾" alone).
  • Heading markup around accordion-item buttons (<h3> typically) if you're building a FAQ or accordion — the APG pattern expects it for landmark/heading navigation; pd-disclosure itself is heading-agnostic.
  • If you server-render aria-expanded="false" on the invoker to avoid a flash before JS upgrades the element, keep it consistent with whether open is present on the matching pd-disclosure — the component overwrites it on connect regardless, so an inconsistent server value only matters for the pre-hydration paint.

Styling — vanilla CSS ​

The animated-collapse trick below uses CSS Grid's 0fr → 1fr row-track transition — the standard grid-first way to animate to/from an intrinsic (unknown) content height without JavaScript measuring anything. It works with this component's timing model specifically because closing is animation-aware (§3): data-state="closed" is applied first while the panel is still visible, the transition plays, and only afterwards does hidden land. Opening, by contrast, removes hidden in the same synchronous tick as data-state="open", so there's no committed "0fr while visible" frame for a plain transition to animate from — pair it with @starting-style if you also want an entrance animation (shown below, optional).

css
/* pd-disclosure's own children become the grid's row content — give the panel
   body a single wrapping element (a <p>, <div>, or <ul> your content usually
   needs anyway) so it's exactly one grid item and the 0fr track fully clips it. */
pd-disclosure {
  display: grid;
  grid-template-rows: 0fr;
  transition: grid-template-rows 200ms ease-out;
}

pd-disclosure[data-state='open'] {
  grid-template-rows: 1fr;
}

pd-disclosure > * {
  overflow: hidden;
  min-height: 0;
}

/* Optional: also animate the entrance. Without this, opening is instant
   (see the note above on why a plain transition can't play on open). */
@starting-style {
  pd-disclosure[data-state='open'] {
    grid-template-rows: 0fr;
  }
}

/* Chevron affordance driven entirely by the ARIA the component already
   manages — no JS, no data-state reads needed on the button itself. */
button[commandfor] .chevron {
  transition: transform 200ms ease-out;
}
button[commandfor][aria-expanded='true'] .chevron {
  transform: rotate(180deg);
}

/* Accordion list layout: grid, not flex — a vertical stack of independent
   rows is exactly what grid-auto-rows gives you for free. */
.accordion {
  display: grid;
  border: 1px solid #ddd;
  border-radius: 8px;
  overflow: hidden;
}
.accordion > button {
  text-align: left;
  padding: 0.75rem 1rem;
}

@media (prefers-reduced-motion: reduce) {
  pd-disclosure,
  button[commandfor] .chevron {
    transition: none;
  }
}

Styling — Tailwind ​

html
<button
  commandfor="shipping"
  command="--pd-toggle"
  class="group flex w-full items-center justify-between gap-2 py-3 text-left font-medium"
>
  Shipping &amp; returns
  <span aria-hidden="true" class="transition-transform duration-200 group-aria-expanded:rotate-180">▾</span>
</button>

<pd-disclosure
  id="shipping"
  class="grid grid-rows-[0fr] transition-[grid-template-rows] duration-200 ease-out
         data-[state=open]:grid-rows-[1fr]
         starting:data-[state=open]:grid-rows-[0fr]
         motion-reduce:transition-none"
>
  <p class="min-h-0 overflow-hidden pb-3 text-sm text-gray-600">
    Free shipping on orders over $50. <a class="underline" href="/returns">Returns policy</a>.
  </p>
</pd-disclosure>
  • data-[state=open]:grid-rows-[1fr] + the base grid-rows-[0fr] is the same trick as the vanilla recipe, expressed as Tailwind's arbitrary-value grid utilities.
  • starting: (Tailwind's @starting-style variant) is what makes the entrance animate too — drop it if you only care about the exit.
  • group-aria-expanded:rotate-180 reads the aria-expanded the component already manages on the group-marked button — no extra state to track.
  • motion-reduce:transition-none is Tailwind's built-in prefers-reduced-motion: reduce guard; no separate media-query block needed.
  • Accordion list wrapper: class="grid overflow-hidden rounded-lg border border-gray-200".

Live demo ​

An accordion of three FAQ items sharing group="faq" — opening one closes the others. The first starts open via a server-rendered open attribute.

Free shipping on orders over $50. Returns accepted within 30 days, unworn and tagged.

<h3>
  <button commandfor="disc-sizing" command="--pd-toggle" class="disclosure-demo-trigger">
    Sizing guide
  </button>
</h3>
<pd-disclosure id="disc-sizing" group="disc-demo" class="disclosure-demo-panel">
  <p>Runs true to size. See the <a href="#">full size chart</a> for exact measurements.</p>
</pd-disclosure>

<h3>
  <button commandfor="disc-care" command="--pd-toggle" class="disclosure-demo-trigger">
    Care instructions
  </button>
</h3>
<pd-disclosure id="disc-care" group="disc-demo" class="disclosure-demo-panel">
  <p>Machine wash cold, tumble dry low. Do not iron printed graphics.</p>
</pd-disclosure>