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
<!-- 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 & 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 —
commandforis a global id reference, not a DOM-position requirement. - Author
openon<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-disclosurehas no opinion on heading structure, that's yours to add.
Accordion (grouped, exclusive)
<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
| Attribute | Type | Default | Notes |
|---|---|---|---|
open | boolean | absent (closed) | Logical state, source of truth. Server-renderable. Reflects the open property; setting/removing it directly bypasses pd:open/pd:close cancelation (reason: 'attribute'). |
group | string | none | Accordion exclusivity key. Opening this disclosure closes every other pd-disclosure in the same root with the same group value. |
id | string | auto-generated | Only filled in when missing (pd-disclosure-N). Set your own when you need a stable, human-readable target for commandfor. |
Properties & methods
| Member | Signature | Notes |
|---|---|---|
open | boolean (get/set) | Get: hasAttribute('open'). Set: reflects the attribute — same cancelation-bypassing behavior as author markup. |
show(reason?) | (reason?: Reason) => boolean | Cancelable open. Returns false if a pd:open listener called preventDefault(); no-op (returns true) if already open. |
hide(reason?) | (reason?: Reason) => boolean | Cancelable close. Returns false if pd:close was prevented; no-op if already closed. |
toggle(force?, reason?) | (force?: boolean, reason?: Reason) => boolean | force 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
| Command | Valid target | Effect |
|---|---|---|
--pd-toggle | pd-disclosure | Flips open ↔ closed. |
--pd-open | pd-disclosure | Opens; no-op if already open (one-way — a second click does nothing). |
--pd-close | pd-disclosure | Closes; 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
| Event | Cancelable | When | detail |
|---|---|---|---|
pd:open | yes | Before opening (from show(), including via a command). | { reason } |
pd:close | yes | Before closing (from hide()). | { reason } |
pd:opened | no | Right after the open attribute and data-state="open" are applied — immediate, no animation wait. | { reason } |
pd:closed | no | After 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:
| Key | Context | Behavior |
|---|---|---|
Tab / Shift+Tab | anywhere | Moves focus to/from the invoker button in normal document order (native). |
Enter / Space | invoker button focused | Activates 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-expandedon everybutton[commandfor="<id>"]invoker, synced totrue/falseat 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
inerton the panel synchronously when it closes, so exit-animation content is immediately absent from the accessibility tree and Tab order.hiddenfollows after the exit animation settles (or immediately on a closed first paint). Opening removes only inertness the component added; an author-suppliedinertattribute is preserved. data-state="open"|"closed"for styling hooks, always present after connect.- The panel's
id, generated only when missing, socommandforalways 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, andaria-expandedsupport 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-disclosureitself 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 whetheropenis present on the matchingpd-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).
/* 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
<button
commandfor="shipping"
command="--pd-toggle"
class="group flex w-full items-center justify-between gap-2 py-3 text-left font-medium"
>
Shipping & 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 basegrid-rows-[0fr]is the same trick as the vanilla recipe, expressed as Tailwind's arbitrary-value grid utilities.starting:(Tailwind's@starting-stylevariant) is what makes the entrance animate too — drop it if you only care about the exit.group-aria-expanded:rotate-180reads thearia-expandedthe component already manages on thegroup-marked button — no extra state to track.motion-reduce:transition-noneis Tailwind's built-inprefers-reduced-motion: reduceguard; 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>