Skip to main content
Official website. How you know

Official websites use .gov

A .gov website belongs to an official government organization in the United States.

Secure .gov websites use HTTPS

A lock or https:// means you’ve safely connected to the .gov website. Share sensitive information only on official, secure websites.

Digital Design System

Accordion

Accordions let users reveal or hide content.

Overview

The accordion always displays a title, optional subtitle, and opened or closed icon. When open, the accordion reveals additional content. 

Closed

A white rectangle displays a title, with a blue plus sign inside a gray circle to the left of it, indicating the accordion is closed.

Opened

A white rectangle displays a title, with a blue minus sign inside a gray circle to the left of it, indicating the accordion is open.

Focused

A dashed line around the accordion component indicates a focused state.

Add an expand/collapse all component to areas with three or more accordions.

Expand Default

A blue plus sign icon in a gray circle to the left of a blue link reading: Expand all

Expand Focus

A dashed line around the expand all component indicates a focused state.

Collapse Default

A blue minus sign icon in a light blue circle to the left of a blue link reading: Collapse all

Collapse Focus

A dashed line around the collapse all component indicates a focused state.

Usage context

When to use

Use accordions when users will only need some information and can skip most other content in the area (as in frequently asked questions).

Accordions can also be used to make long lists more scannable, such a list of resources broken down by category.

When to use something else

When most users will need to see most of the content in an area, use well-formatted text instead.

A good rule of thumb: if an average user will need to open more than two accordions to accomplish their task, don’t use accordions.

Usage guidelines

Toggle the subtitle option to add more context to an accordion. This is useful if the header doesn’t provide enough information scent about what’s inside.

  • nyc.gov mobile portrait view collapsed accordions for: Rent stabilized homes with subtitle The most common type of rent regulation in NYC; Rent controlled homes with subtitle A small number of older buildings with long-term tenants …
  • landscape version of the previous nyc.gov mobile portrait view collapsed accordions

Never nest accordions within accordions.

FAQ: What should I do if my car was booted? With sub accordions How do I enter a boot release code? and Where should I return the boot?

Add an expand/collapse all component for a list of three accordions or more.

  • Services, Browse the most popular government services by category – Expand all, followed by collapsed accordions for Benefits, Complaints, Schools
  • same Services page from previous example image, now showing collapse all and Benefits expanded to show links to Cash help during an emergency…, Voucher that pay part of your rent…, and Vouchers that help cover the cost of childcare.

Accordions should always be closed by default so that users can scan all the options quickly and click on the one that’s most relevant to their needs.

Desktop view of the NYC Services page, subheading is a single line of text - Expand all, followed by 4 collapsed buttons for Benefits, Complaints, Trash…, & Schools.Mobile portrait view of the NYC Services page, subheading covers 2 lines of text - Expand all, followed by 4 collapsed buttons for Benefits, Complaints, Trash…, & Schools.

Custom element

Accordions can be invoked via the nyc-accordion custom element. This will generate an accessible accordion markup structure and functionality when given a heading element as a first child; sibling elements will be added to the accordion panel. Whenever the same heading type is encountered a new accordion group will be created.

This code is for reference only. The library is currently in beta. Check back for future releases.

Taxes

Content about taxes

Fines

Parking tickets

Content about parking tickets

<nyc-accordion>
  <h4>Taxes</h4>
  <p>Content about taxes</p>
  <h4>Fines</h4>
  <p><strong>Parking tickets</strong></p>
  <p>Content about parking tickets</p>
</nyc-accordion>

Subheadings

Subheadings can be included by wrapping your heading tag and including a sibling.

This code is for reference only. The library is currently in beta. Check back for future releases.

Taxes

Learn about taxes

Content about taxes

<nyc-accordion>
  <article>
    <header>
      <h4>Taxes</h4>
      <p>Learn about taxes</p>
    </header>
    <p>Content about taxes</p>
  </article>
</nyc-accordion>

Expand all

Include a button to toggle all accordions with the data-expand-all-button attribute

This code is for reference only. The library is currently in beta. Check back for future releases.

Taxes

Content about taxes

Complaints

Make a complaint

Trash

Learn about trash pickup

<nyc-accordion data-expand-all-button>
  <h4>Taxes</h4>
  <p>Content about taxes</p>
  <h4>Complaints</h4>
  <p>Make a complaint</p>
  <h4>Trash</h4>
  <p>Learn about trash pickup</p>
</nyc-accordion>