Skip to content
Tutorials Center
My learning

Topics

Lesson 73 of 122 ยท Interactive Elements

Collapsible Sections with Details

Build collapsible sections and accordions with details and summary, open them by default, group them with name, react to the toggle event and style the marker.

Long pages often contain information that only some readers need: answers to frequently asked questions, the fine print of an offer, an optional hint in an exercise. Showing all of it at once buries the important parts. Hiding it behind a "click to expand" control keeps the page calm while leaving everything one click away.

HTML has a built-in element for exactly this: <details>. It needs no JavaScript, it works with the keyboard out of the box, and screen readers announce it as something that can be expanded and collapsed. In this lesson you will build collapsible sections, turn a group of them into an accordion, react when they open and close, and restyle the little triangle.

The basic pattern

A disclosure widget has two parts:

  • <details> wraps the whole thing.
  • <summary>, its first child, is the label that is always visible. Clicking it (or pressing Enter or Space while it has focus) shows or hides everything else inside <details>.
A collapsible section

Everything after the <summary> is the hidden content. It can be any flow content: paragraphs, lists, images, tables, even a form.

A few rules keep the widget working well:

  • Put the <summary> first. If you leave it out, the browser invents a label (usually the word "Details" in the reader's language), which is rarely what you want.
  • Keep the summary short and descriptive. It works like a button label, so "Delivery times" beats "Click here".
  • Avoid putting links, buttons or form fields inside the <summary>. The summary itself is already the interactive control, and nesting other controls in it confuses both mouse and keyboard users.

You can learn more about headings and labels that describe content well in Headings and Paragraphs.

Open by default: the open attribute

<details> starts closed. Add the boolean open attribute to show the content when the page loads:

HTML
<details open>
  <summary>Before you start</summary>
  <p>Make sure you have a text editor and a web browser installed.</p>
</details>

The browser keeps this attribute in sync with what the user does. When someone expands the widget, open is added; when they collapse it, open is removed. That means you can read the current state in JavaScript with element.open, set it with element.open = true, and target it in CSS with the selector details[open].

Find in page. In current Chromium-based browsers, searching the page with Ctrl+F (Cmd+F on a Mac) also finds text inside closed <details> elements and opens them automatically, and other browsers have been adding the same behavior. Collapsed content is hidden, not deleted.

Exclusive accordions with name

An accordion is a stack of collapsible sections where opening one closes the others. You used to need JavaScript for that. Now you can give several <details> elements the same name value, and the browser lets only one of them be open at a time:

An exclusive accordion

Open "Pro plan" and watch "Free plan" close by itself. A few details about how grouping works:

  • Elements belong to the same group when they share the same name value and are in the same document (or shadow tree, which you will meet in Templates and Web Components). They don't need to be siblings.
  • Nothing forces one section to stay open. The reader can still close all of them.
  • If you mark several grouped elements with open in your HTML, the browser keeps only the first one open.

Browser support. The name attribute on <details> works in all current major browsers (it arrived during 2023โ€“2024). In an older browser the attribute is simply ignored, so your sections still expand and collapse โ€” they just don't close each other. That's a safe fallback.

Think twice before making an accordion exclusive. If readers need to compare two sections side by side, closing one automatically gets in their way. Exclusive accordions suit content where people read one item at a time, like a step-by-step guide or a set of pricing tiers.

Reacting to the toggle event

Every time a <details> element opens or closes, it fires a toggle event. The event fires after the change, so open already holds the new state. This is handy for loading content only when it's needed, or for remembering which sections a reader expanded.

The toggle event

The toggle event does not bubble, so attach the listener to each <details> element rather than to a common parent. (If you really want one listener for many widgets, pass true as the third argument of addEventListener to catch the event during the capture phase.) You will learn more about listeners in Event Attributes and Event Listeners.

Styling the marker

By default the summary shows a small triangle that rotates when the widget opens. In modern browsers the summary is displayed like a list item, and that triangle is its marker. You can restyle it with the ::marker pseudo-element, or remove it and draw your own:

A custom marker

Here is what each part does:

  • list-style: none on the summary removes the standard marker.
  • The ::-webkit-details-marker rule hides it in older versions of Safari, which used a non-standard marker. It does no harm elsewhere.
  • summary::before draws a plus sign, and details[open] summary::before swaps it for a minus sign.

If you only want to change the triangle's color or size, keep it and style it directly: summary::marker { color: crimson; }. Only a few properties work on ::marker (such as color, font-size and content), so draw your own icon when you need more control.

Animating the opening. Newer browsers support a ::details-content pseudo-element that targets the hidden part, which makes smooth open and close animations possible with CSS alone. Support is still uneven, so treat such animations as a progressive enhancement that the page doesn't depend on.

When to use details โ€” and when not to

<details> is the right choice for any "show more" disclosure: FAQs, optional explanations, long code samples, spoilers, filters in a sidebar. It's semantic, accessible and costs nothing.

It's not the right tool for:

  • Menus and pop-up panels that should float above the page and close when the user clicks elsewhere. Use the popover attribute from Popovers instead.
  • Messages that need an answer before the user can continue. That's a job for a modal dialog.
  • Tabs. A tab interface shows exactly one panel and has its own keyboard pattern. An exclusive accordion looks similar but behaves differently.
  • Important content that most readers must see. Hiding it makes it easy to miss.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where must the <summary> element go?

    The <summary> must be the first child. Everything after it is the content that gets shown and hidden.
  2. 2. Three <details> elements share name="faq". What happens when the reader opens the second one?

    Elements with the same name form an exclusive group, so opening one closes the others.
  3. 3. Inside a toggle event listener, how do you know whether the element just opened?

    The event fires after the change, so open is already true when the element has just opened and false when it has just closed.
  4. 4. Which CSS hides the default triangle in modern browsers?

    The summary is displayed like a list item, so list-style: none removes its marker. There is no marker: off property, and hiding details would hide the whole widget.

Summary

  • <details> creates a collapsible section; its first child, <summary>, is the always-visible label.
  • The boolean open attribute shows the content and stays in sync with what the user does.
  • Give several <details> elements the same name to build an exclusive accordion.
  • The toggle event fires after each change; read element.open to see the new state. It doesn't bubble.
  • Restyle the marker with summary::marker, or remove it with list-style: none and draw your own.
  • Use popovers for floating panels and dialogs for messages that need a response.

Next lesson: Dialogs and Modals.