Design Pattern

Accordion

An accordion is a UI pattern that toggles the visibility of multiple sections. Using HTML's details and summary elements, you can implement an accessible accordion without any JavaScript.

Difficulty: Beginner Category: Navigation

When to use / not use

Use it when

  • When you want to organize and display multiple questions and answers, such as FAQs
  • When you want to divide long content into sections and reveal it progressively
  • When you want to group items by category, such as settings panels or filters

Don't use it when

  • When all content should always be visible
  • When there are only 1–2 items → use a disclosure instead
  • When content needs to be compared frequently → consider tabs or a side-by-side layout

Anatomy

1 Summary (section title)
2 Content panel (shown when expanded)
3 Toggle icon (▶ / ▼)
  1. Summary — The <summary> element. The trigger that toggles open/closed via click or keyboard
  2. Content panel — The body inside <details>. Displayed only when expanded
  3. Icon — A visual indicator of the open/closed state. Controlled with CSS

HTML Structure

Key points

  • Using <details> and <summary> provides toggle functionality without JavaScript
  • Place <summary> as the first child of <details>
  • For an exclusive accordion, set the same name attribute on each details element
  • Add the open attribute to items that should start expanded

CSS Implementation

Styling points

  • Hide the default triangle marker with ::-webkit-details-marker and list-style: none
  • Implement the toggle icon as a pseudo-element and rotate/transform it via the [open] selector
  • Borders and border-radius can group multiple items into a card-like block for better visibility
  • Change the background color on hover to signal that the item is clickable

Accessibility

WCAG 4.1.2 Name, Role, Value

When you use <details> and <summary>, the browser conveys the expanded/collapsed state to assistive technology.

WCAG 2.1.1 Keyboard

<summary> is natively focusable and can be toggled with Enter / Space.

Keyboard operation

  • Use Tab to move focus between accordion headers
  • Press Enter or Space to toggle open/closed
  • In an exclusive accordion, opening one item automatically closes the others

Live Demo

Accordion built with the details element

The simplest implementation using native HTML details / summary.

PreviewFullscreen

Exclusive accordion

A pattern where only one item opens at a time, using the same name attribute.

PreviewFullscreen

Custom styling

A variation that hides the default triangle and applies a custom look.

PreviewFullscreen

Common mistakes

Building your own with div + JavaScript

When native details / summary would do, rolling your own easily accumulates accessibility and state-management debt.

Indicating state with icons only

The state must be conveyed not just visually, but also to assistive technology.

Hiding important content

Hiding must-read information inside an accordion invites oversights and mis-operations.

Nesting too deeply

Nesting accordions inside accordions tends to make the information structure complex.