Add an accessible disclosure with details and summary

Learning objectives

Build a native disclosure; set its initial state; explain boolean attribute behavior.

Prerequisites

Understand nesting and keyboard focus.

Understand the markup

A disclosure hides supporting information until the reader asks for it. The details element provides this interaction without custom JavaScript. Its first summary child supplies the visible label. Place the supplementary content after summary so it becomes available when the disclosure opens.

Choose a label that describes the information inside, such as What is included in membership? A vague label such as More makes a page with several disclosures difficult to scan. Essential instructions should remain visible instead of being concealed behind a disclosure that readers may never open.

The open boolean attribute sets the initial expanded state. Omit it to start collapsed. The spelling open="false" still starts expanded: HTML boolean attributes are true when present. A script can read or assign the details element's open property, and the toggle event reports a state change when additional behavior is necessary.

Native disclosure controls work with keyboard interaction in supporting browsers. Test any heavy styling that changes the summary marker or display type, because it can affect discoverability and browser behavior. The disclosure is not a modal dialog: it does not block the page, move focus into a separate window, or require a focus trap.

Try a working example

<h1>Delivery questions</h1>
<details>
  <summary>When will my order arrive?</summary>
  <p>Most orders arrive within three working days.</p>
</details>

Expected output

The question is initially visible. Activating it reveals the delivery answer; activating it again collapses the answer.

Another example

<details open>
<summary>What should I bring?</summary>
<p>Bring a notebook and a reusable water bottle.</p>
</details>

Common mistakes

Do not put the summary after the hidden content. Avoid adding a second click handler that toggles the state again after the browser already toggles it.

Accessibility and browser notes

Keep a visible keyboard focus indicator on summary. Native semantics usually remove the need for role="button" or manual aria-expanded state.

Check your work

Test the disclosure without using a pointer. Move focus to its summary with Tab, then activate it with the keyboard and read the newly revealed content. Repeat after applying styles. If your custom icon rotates when open, make that decorative change depend on the open attribute so its appearance cannot drift away from the native state.

Practice

Create an initially expanded disclosure named Is the workshop free? with an answer that explains registration is required.

<details open><summary>Is the workshop free?</summary>
<p>Yes. Register in advance so we can reserve your place.</p></details>

Related lesson

HTML introduction: describe your first page

Specifications and further reading

WHATWG HTML Living Standard

Choose disclosure, accordion, or dialog by the task

A disclosure keeps secondary information in the reading flow. A dialog represents a separate interaction that may require deliberate focus movement; a tab interface switches between related views. Choosing details because it is convenient does not make it an appropriate replacement for every expandable or overlaying interface. Start with the user's task and the expected navigation behavior.

Related details elements can use a shared name to form a native exclusive group in supporting browsers. Treat this as progressive enhancement: the information should still be usable if several panels remain open. Test browser support for the exact grouping behavior you need rather than assuming support for details also guarantees every newer related feature.

Avoid putting multiple independent interactive controls into summary when it makes activation ambiguous. A short descriptive label is usually easier to operate and understand. If a panel contains a long answer, preserve its headings and paragraphs so opening it reveals useful structure instead of an undifferentiated block of text. Finally, make sure essential warnings are not hidden in a panel that a reader can reasonably skip.