Skip to content

Disclosure

Show and hide, a section that opens in place and a group row in a list.

<details class="cap-disclosure">
  <summary>Why is example.com marked degraded?</summary>
  <div class="cap-disclosure-body">
    <p>Its median response over the last hour is 2.4 seconds, more than three times its median over the week (0.6 seconds).</p>
  </div>
</details>

Installation

// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/disclosure.css";
import { enhance } from "capsomer/behavior/disclosure";

enhance();

Usage

<details class="cap-disclosure" name="limits">
  <summary>Why is example.com marked degraded?</summary>
  <div class="cap-disclosure-body"><p>Its median response over the last hour is 2.4 seconds.</p></div>
</details>

<div class="cap-group" data-cap="disclosure">
  <button type="button" class="cap-group-toggle" aria-expanded="false" aria-controls="notices-rows">
    <span class="cap-group-label">Notices</span><span class="cap-sr-only">, </span><span class="cap-group-count">4</span>
  </button>
  <ul class="cap-group-rows" id="notices-rows" hidden>
    <li>api: 3 dependency updates waiting</li>
    <!-- a second level: <li class="cap-group-nest"><div class="cap-group" data-cap="disclosure">...</div></li> -->
  </ul>
</div>
<button type="button" class="cap-link-btn cap-expand-toggle" data-cap="expand" aria-expanded="false" aria-controls="email-preview"
  data-open-label="Hide email" data-closed-label="View email"><span class="cap-expand-label">View email</span></button>
<div class="cap-expand-region" id="email-preview" hidden>...</div>

<tr><th scope="row"><button type="button" class="cap-link-btn cap-expand-toggle cap-expand-row" data-cap="expand" aria-expanded="false"
  aria-controls="evt-1-payload"><span class="cap-expand-label">invoice.payment_failed</span><span class="cap-sr-only"> payload</span></button></th>...</tr>
<tr class="cap-expand-detail" id="evt-1-payload" hidden><td colspan="3">...</td></tr>

Examples

Section, open

<details class="cap-disclosure" open>
  <summary>What the watcher checks</summary>
  <div class="cap-disclosure-body">
    <p>Every five minutes it asks each site's health route for its commit, and whether its database and queue respond.</p>
    <p>A site with no health route is asked for its home page; a 200 from there counts as alive and nothing more.</p>
  </div>
</details>

Sections that open one at a time

<details class="cap-disclosure" name="limits" open>
  <summary>Worker requests</summary>
  <div class="cap-disclosure-body"><p>100,000 a day on the free plan. Resets at 00:00 UTC.</p></div>
</details>
<details class="cap-disclosure" name="limits">
  <summary>D1 rows read</summary>
  <div class="cap-disclosure-body"><p>5 million a day on the free plan. At the limit, reads fail until the reset.</p></div>
</details>
<details class="cap-disclosure" name="limits">
  <summary>KV writes</summary>
  <div class="cap-disclosure-body"><p>1,000 a day on the free plan. At the limit, the watcher cannot save its pass.</p></div>
</details>

Group row, collapsed, with its count

<div class="cap-group" data-cap="disclosure">
  <button type="button" class="cap-group-toggle" aria-expanded="false" aria-controls="notices-rows"><span class="cap-group-label">Notices</span><span class="cap-sr-only">, </span><span class="cap-group-count">4</span></button>
  <ul class="cap-group-rows" id="notices-rows" hidden>
    <li>api: 3 dependency updates waiting, none urgent</li>
    <li>docs: a reviewer's flag has waited 2 days</li>
    <li>web: the TLS certificate renews in 21 days</li>
    <li>blog: no backup reported yet</li>
  </ul>
</div>

Group row, expanded, two levels

<div class="cap-group" data-cap="disclosure">
  <button type="button" class="cap-group-toggle" aria-expanded="true" aria-controls="updates-rows"><span class="cap-group-label">Dependency updates</span><span class="cap-sr-only">, </span><span class="cap-group-count">5</span></button>
  <ul class="cap-group-rows" id="updates-rows">
    <li>api: vite 8.3.1 to 8.4.0</li>
    <li>api: wrangler 4.40.0 to 4.41.2</li>
    <li class="cap-group-nest">
      <div class="cap-group" data-cap="disclosure">
        <button type="button" class="cap-group-toggle" aria-expanded="false" aria-controls="docs-updates"><span class="cap-group-label">docs</span><span class="cap-sr-only">, </span><span class="cap-group-count">3</span></button>
        <ul class="cap-group-rows" id="docs-updates" hidden>
          <li>react 19.3.0 to 19.3.1</li>
          <li>react-dom 19.3.0 to 19.3.1</li>
          <li>@base-ui/react 1.8.0 to 1.8.2</li>
        </ul>
      </div>
    </li>
  </ul>
</div>

Group row in a heading

<div class="cap-group" data-cap="disclosure">
  <h3 class="cap-group-heading"><button type="button" class="cap-group-toggle" aria-expanded="false" aria-controls="queue-done-rows"><span class="cap-group-label">Finished jobs</span><span class="cap-sr-only">, </span><span class="cap-group-count">12</span></button></h3>
  <ul class="cap-group-rows" id="queue-done-rows" hidden>
    <li>Run the browser tests for capsomer</li>
    <li>Refresh the uptime strip fixtures</li>
  </ul>
</div>

Summary hover and pressed

<details class="cap-disclosure">
  <summary>A summary under the pointer</summary>
  <div class="cap-disclosure-body"><p>The row takes the raised tint.</p></div>
</details>
<details class="cap-disclosure">
  <summary>A summary being pressed</summary>
  <div class="cap-disclosure-body"><p>The row takes the sunken tint.</p></div>
</details>

Accordion variant (shadcn's flat look), comfortable density

<div data-density="comfortable" id="accordion-specimen">
  <details class="cap-disclosure" data-variant="accordion" name="faq" open>
    <summary>Is it accessible?</summary>
    <div class="cap-disclosure-body"><p>Yes. It is a native details element, so it works with a keyboard and a screen reader.</p></div>
  </details>
  <details class="cap-disclosure" data-variant="accordion" name="faq">
    <summary>Is it animated?</summary>
    <div class="cap-disclosure-body"><p>The panel grows and shrinks where the browser can animate to auto height, and only when motion is allowed.</p></div>
  </details>
  <details class="cap-disclosure" data-variant="accordion" name="faq">
    <summary>Can it be styled?</summary>
    <div class="cap-disclosure-body"><p>It takes its sizes from the density tokens.</p></div>
  </details>
</div>

Card variant (a questions list), one open at a time

<ul id="card-specimen" style="display: grid; gap: var(--space-4); margin: 0; padding: 0; list-style: none">
  <li><details class="cap-disclosure" data-variant="card" name="card-faq" open>
    <summary>Does it change my billing settings?</summary>
    <div class="cap-disclosure-body"><p>No. It reads the account and changes nothing.</p></div>
  </details></li>
  <li><details class="cap-disclosure" data-variant="card" name="card-faq">
    <summary>Can I cancel anytime?</summary>
    <div class="cap-disclosure-body"><p>Yes, from the settings page.</p></div>
  </details></li>
</ul>

Inline, with the sign marker: in a post and under a step

<div id="inline-specimen">
  <p>The plaque counts below come from three plates per dilution.</p>
  <details class="cap-disclosure" data-variant="inline" data-marker="sign" id="inline-closed">
    <summary>Show the counts</summary>
    <div class="cap-disclosure-body"><p>10<sup>-6</sup>: 212, 198, 205. 10<sup>-7</sup>: 22, 19, 25.</p></div>
  </details>
  <details class="cap-disclosure" data-variant="inline" data-marker="sign" open id="inline-open">
    <summary>How the titer is worked out</summary>
    <div class="cap-disclosure-body"><p>The mean count at a countable dilution, divided by the volume plated and the dilution.</p></div>
  </details>
  <ol>
    <li>Plate 100 microliters of each dilution in top agar.
      <details class="cap-disclosure" data-variant="inline" data-marker="sign" data-print="hide" id="step-calc">
        <summary>Calculator: titer from a plate count</summary>
        <div class="cap-disclosure-body">
          <p>The fields start on the lab's worked example. Enter your own numbers.</p>
          <label class="cap-field-label" for="calc-count">Plaques counted</label>
          <input class="cap-input" id="calc-count" inputmode="numeric" value="205">
        </div>
      </details>
    </li>
  </ol>
</div>

Expand toggle: a step's email, and a table row's detail

<div id="expand-specimen">
  <p>Reminder email sent 2 hours ago. Opened.
    <button type="button" class="cap-link-btn cap-expand-toggle" data-cap="expand" aria-expanded="false" aria-controls="email-preview" data-open-label="Hide email" data-closed-label="View email"><span class="cap-expand-label">View email</span></button>
  </p>
  <div class="cap-expand-region" id="email-preview" hidden>
    <p>Your card ending 4242 was declined. Update it here to keep your plan.</p>
  </div>
  <div class="cap-table-wrap" role="region" aria-label="Webhook events" tabindex="0">
    <table class="cap-table">
      <caption>Webhook events</caption>
      <thead><tr><th scope="col">Event</th><th scope="col">Status</th><th scope="col">Received</th></tr></thead>
      <tbody>
        <tr>
          <th scope="row"><button type="button" class="cap-link-btn cap-expand-toggle cap-expand-row" data-cap="expand" aria-expanded="false" aria-controls="evt-1-payload" id="evt-1"><span class="cap-expand-label">invoice.payment_failed</span><span class="cap-sr-only"> payload</span></button></th>
          <td>Processed</td><td>09:12</td>
        </tr>
        <tr class="cap-expand-detail" id="evt-1-payload" hidden>
          <td colspan="3"><pre tabindex="0" aria-label="invoice.payment_failed payload">{ "id": "evt_sample", "type": "invoice.payment_failed" }</pre></td>
        </tr>
      </tbody>
    </table>
  </div>
</div>

Compact card, a form behind its title

<p class="cap-muted">Small cards beside each other on an admin page: each opens in place to a form or a list ("Edit sponsor", "Add an item", "Chair (3)").</p>
<ul id="card-sm-specimen" style="display: grid; gap: var(--space-4); margin: 0; padding: 0; list-style: none">
  <li><details class="cap-disclosure" data-variant="card" data-size="sm" open>
    <summary>Edit sponsor</summary>
    <div class="cap-disclosure-body">
      <form>
        <label class="cap-field-label" for="sponsor-name">Name</label>
        <input class="cap-input" id="sponsor-name" type="text" value="Example Co" />
        <button type="submit" class="cap-btn" data-size="sm">Save sponsor</button>
      </form>
    </div>
  </details></li>
  <li><details class="cap-disclosure" data-variant="card" data-size="sm">
    <summary>Chair (3)</summary>
    <div class="cap-disclosure-body"><ul><li>Alex Rivera</li><li>Sam Lee</li><li>Jordan Park</li></ul></div>
  </details></li>
  <li><details class="cap-disclosure" data-variant="card" data-size="sm">
    <summary>Add an item</summary>
    <div class="cap-disclosure-body"><p>Choose what the session holds.</p></div>
  </details></li>
</ul>

A site's own card: the triangle marker, its spacing by token; and an inline section with it

<p class="cap-muted">A compact card with data-marker="triangle" and the disclosure tokens set as txasm's cards were; then an inline section with the triangle.</p>
<ul style="display: grid; gap: var(--space-4); margin: 0; padding: 0; list-style: none; --disclosure-pad: var(--space-4); --disclosure-summary-pad: 0; --disclosure-summary-min-h: var(--target); --disclosure-body-pad: 0; --disclosure-body-gap: var(--space-4)">
  <li><details class="cap-disclosure" data-variant="card" data-size="sm" data-marker="triangle" open>
    <summary>Session chairs (2)</summary>
    <div class="cap-disclosure-body"><ul><li>Alex Rivera</li><li>Sam Lee</li></ul></div>
  </details></li>
  <li><details class="cap-disclosure" data-variant="card" data-size="sm" data-marker="triangle">
    <summary>Add a chair</summary>
    <div class="cap-disclosure-body"><p>Choose a member.</p></div>
  </details></li>
</ul>
<details class="cap-disclosure" data-variant="inline" data-marker="triangle" open>
  <summary>Why this abstract was returned</summary>
  <div class="cap-disclosure-body"><p>It ran past the 300-word limit.</p></div>
</details>

Group row, pressed and disabled

<div class="cap-group" data-cap="disclosure">
  <button type="button" class="cap-group-toggle" aria-expanded="false" aria-controls="pressed-rows"><span class="cap-group-label">Pressed</span><span class="cap-sr-only">, </span><span class="cap-group-count">2</span></button>
  <ul class="cap-group-rows" id="pressed-rows" hidden><li>One</li><li>Two</li></ul>
</div>
<div class="cap-group" data-cap="disclosure">
  <button type="button" class="cap-group-toggle" disabled aria-expanded="false" aria-controls="disabled-rows"><span class="cap-group-label">Archived</span><span class="cap-sr-only">, </span><span class="cap-group-count">0</span></button>
  <ul class="cap-group-rows" id="disabled-rows" hidden></ul>
</div>

API reference

Disclosure

PropTypeRequiredDoes
summaryReactNodeYes
childrenReactNodeYes
namestringSections that share a name open one at a time.
defaultOpenboolean
variant"accordion" | "card" | "inline""accordion": shadcn's flat look, a rule between items and the chevron at the end. "card": each section its own rounded card, with a plus that turns to a cross. "inline": no box, a rule above and below, the title in the link color (a post's "Show the data", a procedure step's calculator).
size"sm""sm" on the card: the compact card for a form or a list behind its title.
marker"sign" | "triangle""sign": a mono plus that becomes a minus, in place of the chevron. "triangle": a small triangle at the start, as the browser's own, in place of the variant's chevron or plus.
print"hide"Sections are open on paper. "hide" leaves this one off the printed page (a calculator).
classNamestring

Group

PropTypeRequiredDoes
labelstringYesWhat the rows are: "Notices".
countnumberYesHow many rows it holds; read as "Notices, 4".
childrenReactNodeYesThe grouped rows, as <li> elements.
defaultExpandedboolean
holdsCriticalbooleanCritical rows are never collapsed: true keeps the group open.
headingLevel2 | 3 | 4Puts the button in a heading of this level, so a person moving by heading finds the group.

ExpandToggle

PropTypeRequiredDoes
labelReactNodeYesWhat the button says while the region is closed ("View email") and while open ("Hide email").
openLabelReactNode
openbooleanYes
onToggle() => voidYes
controlsstringYesThe id of the region it shows or hides.
classNamestring

ExpandRows

PropTypeRequiredDoes
row(toggle: ReactNode) => ReactNodeYesThe row's cells. Put toggle (the button) in the first cell.
nameReactNodeYesWhat the button names ("customer.subscription.updated"); a hidden " details" follows it unless toggleSuffix says otherwise ("payload").
toggleSuffixstring
detailReactNodeYesThe detail, across every column of the table.
columnsnumberYes
defaultOpenboolean

Functions

FunctionSignatureDoes
useExpand(defaultOpen?: boolean): { open: boolean; setOpen: Dispatch<SetStateAction<boolean>>; toggle: { "aria-expanded": boolean; "aria-controls": string; onClick: () => void; }; region: { ...; }; }One region shown or hidden by a toggle beside it: the state, and the props for the button and the region. For a list of rows that open one at a time, keep the open id in the parent instead.
setGroup(button: HTMLElement, expanded: boolean): voidShow and hide. A <details class="cap-disclosure"> needs no JavaScript. This module runs the group rows (.cap-group): a button with aria-expanded and aria-controls that shows or hides the rows it groups. Two levels at most, and a critical item is never inside a collapsed group. No framework; the React wrapper uses the same rules. Shows or hides what one button controls (a group's rows, a step's email, the warnings past the cap) and keeps the button's state true. A button with data-open-label says that while open ("Fewer warnings") and its own words again when closed (data-closed-label, else the words it had); an expand toggle's words are its .cap-expand-label.
toggleGroup(button: HTMLElement): void
groupDepth(group: Element): numberHow deep a group sits: 1 for a group at the top, 2 for one inside another.
enhanceExpand(root?: ParentNode): () => voidAttaches to every expand toggle ([data-cap="expand"], a button with aria-expanded and aria-controls) under root: a press shows or hides the region it names (a step's email, a table row's detail row). Returns a function that detaches them.
enhance(root?: ParentNode): () => voidAttaches to every [data-cap="disclosure"] group under root. A collapsed group that holds a critical item ([data-tone="crit"]) is opened, because critical items are never hidden. Returns a function that detaches them.

CSS variables

VariableDefault
--disclosure-body-gap0
--disclosure-body-pad0 var(--space-4) var(--space-4)
--disclosure-marker-gapvar(--space-3)
--disclosure-pad0
--disclosure-summary-min-hmax(var(--target), var(--control))
--disclosure-summary-padvar(--space-2) var(--space-4)

Parts and data attributes

ClassIs
.cap-disclosurethe root
.cap-disclosure-bodya part
.cap-expand-detailits own class
.cap-expand-regionits own class
.cap-expand-toggleits own class
.cap-groupits own class
.cap-group-countits own class
.cap-group-headingits own class
.cap-group-nestits own class
.cap-group-rowsits own class
.cap-group-toggleits own class
AttributeValues
data-markersign triangle
data-printhide
data-sizesm
data-variantaccordion card inline
StateRead from
:activethe platform
:disabledthe platform
:focus-visiblethe platform
:hoverthe platform
[aria-disabled="true"]an attribute
[aria-expanded="true"]an attribute
[hidden]an attribute
[open]an attribute

Accessibility

KeyDoes
TabReaches each summary and each group button
Enter or Space on a summaryOpens or closes the section
Enter or Space on a group buttonShows or hides its rows; aria-expanded follows
  • summary is announced as a button with its expanded state by the browser; the group button sets aria-expanded itself.
  • Hidden rows use hidden, so they leave the accessibility tree and the tab order.
  • Forced colors: the chevrons take the text color.