An accordion is used to show and hide content.


Default accordion
Loading story...

View in Pajamas UI Kit →


Numbered diagram of an accordion structure
Accordion structure
  1. Caret: Identifies when the accordion is open or closed. Pointing down is open. Pointing right is closed.
  2. Title: Identifies the title of the accordion.
  3. Body: Contains the content of an accordion.


When to use

  • Displaying and grouping additional information.
  • Adding granular control over the information on a given page.
  • Shortening pages to reduce scrolling.

When not to use

  • Displaying critical system information or a primary action to be taken on the page. (for example, alerts, confirmation or cancellation buttons).
  • Displaying navigation elements such as tabs.
  • Displaying links pointing to sections of the same page, instead use a semantic HTML list.
  • Creating hierarchy levels by nesting them within each other. If you need to add hierarchy to the content use a tree.
  • Displaying a set of visual components following the same style, prefer using Collapsable.(TODO: Add link to collapsable).



To reduce cognitive load and time to task completion, the icon should be located before the header, so users always click on the same spot to expand/collapse the accordion. The icon should always reflect the state of the accordion (expanded or collapsed).

The following icons should be used:

Collapsed state iconExpanded state icon
Chevron right icon
Chevron down icon

The affordance of the chevron means that additional information can be found "under" the header.

Just like modals, the header of an accordion could be a question or a title. Either way, headers should give context about the underlying content in a concise and actionable way. Examples of headers can be "What can GitLab offer me?", or "More options".


The content in the accordion body should be visually different from the rest of the page as it is secondary information. The accordion body is always displayed below its header. Use spacing (margin/padding/horizontal rule) and/or hierarchy (font size, color) to structure the body content. The content should directly relate to the header. For example, the content for "What can GitLab offer me?" could be "GitLab helps organizations deliver better products faster, increase operational efficiencies, and reduce security and compliance risks...".


Users should be able to expand and collapse the body by clicking or tapping a single area containing the accordion header and icon. Changing the accordion state will trigger an animation.

Multiple accordions

In the case of a page layout built around several accordions following each other (for example, FAQ page where each question is an accordion), changing one accordion state does not reflect on the other, each accordion would need to be expanded/collapsed individually by users.


Use proper semantic markup, so that users of screen readers are aware of the states of the accordion.

  • The aria-controls attribute should define that the header is acting as a trigger to reveal content (the accordion body).
  • The aria-expanded attribute should be used to indicate the state of the accordion.
  • After a user expands/collapses the accordion, the focus should remain on the area wrapping the header and the icon, so that the user can trigger the accordion using the keyboard.
  • The accordion should not rely on JavaScript to reveal the body content.


Last updated at: