Accordion

Guidance

When to use the accordion component

• If users will only need a few specific pieces of content within a page.

• If you have only a small space to display a lot of content.

When to consider something else

• If users need to see most or all of the information on a page. Use well-formatted text instead.

• If there is not enough content to warrant condensing. Accordions increase cognitive load and interaction cost because users have to make decisions about what headers to click on.

Usability guidance

• Make the entire header selectable. Allow users to click anywhere in the header area to expand or collapse the content; a larger target is easier to manipulate.

• Give interactive elements enough space. Make sure interactive elements within the collapsible region are far enough from the headers that users don’t accidentally trigger a collapse. (The exact distance depends on the device.)

Accessibility

• Code header areas in the accordion as buttons. Using a <button type="button"> assures accordions are usable with both screen readers and keyboards.

• Use aria-expanded on buttons to express an accordion’s default state. Buttons should state if they are expanded by default with aria-expanded="true". The aria-expanded="false" attribute will be added to other buttons when the accordion is initialized by the JavaScript.

• Use unique ids. Each button has a unique name, aria-controls="id", that associates the control with the appropriate region by referencing the controlled element’s id.

• Accordions use javascript to set the hidden values of their content areas. Each content area will have its hidden attribute set by the component, depending on its corresponding button’s aria-expanded attribute. To ensure your content is accessible in the event that the JavaScript does not load or is disabled, you should not manually set hidden on any of your content areas.

Using the accordion component

• Multiselectable accordion groups. Add the data-allow-multiple attribute to any usa-accordion to create a multiselectable accordion group.

• Default an accordion button to open. Add the aria-expanded="true" attribute to any usa-accordion__button to have that section open by default at page load.

Accordion variants