use UI

Accordion vs Disclosure

They look like the same thing at two sizes, and mostly they are — a button, a panel, `aria-expanded`. The difference is the relationship, not the count. An accordion is a group, and the only thing the group actually buys you is that opening one section closes the last. Take that away and you do not have an accordion any more; you have disclosures stacked on top of each other, which is a perfectly good thing to have and is what most so-called accordions really are. Worth asking the earlier question too: whether the content needs hiding at all. Collapsed text is read less, and that cost is paid whichever of the two you pick.

If opening one section should close another, it is an accordion. Otherwise it is disclosures, however many there are.

Accordion

A set of headings that each reveal a panel of content, grouped so that they behave as one component.

Reach for it when

  • The sections are parallel and short — an FAQ, a spec sheet, a list of policies — and no one reads all of them.
  • Vertical space is scarce and the headings work as a table of contents for what is below.
  • Settings that are grouped and rarely touched: collapsed by default is the honest state.
  • Only one section is relevant at a time, so closing the previous one is genuinely helpful rather than annoying.

Avoid it when

  • Most of the content will actually be read. Every section then costs a click, and hidden content is measurably less read.
  • Two sections need to be compared. An exclusive accordion makes that impossible by design.
  • There is only one section — that is a disclosure, and wrapping it in a group buys nothing.
  • The content matters for search or deep links. Collapsed panels are not found by Ctrl+F unless you opt into `hiddenUntilFound`.

Disclosure

A button that reveals or hides one associated section of content, independent of any other section.

Reach for it when

  • The content is genuinely secondary: advanced options, technical detail, a full stack trace.
  • A long passage needs a “read more” so the page stays scannable.
  • A row or card has detail that only some users want, and hiding it keeps the list readable.
  • You were about to build an accordion for exactly one section.

Avoid it when

  • The user needs to see the information. Hidden content is read less, and no styling fixes that.
  • It is an error, warning or anything the user must act on — those never collapse.
  • It hides a required form field. If it must be filled in, it must be visible.
  • The label cannot say what is inside. “More” gives the user nothing to decide with.