Components

Accordion

An accordion is a list of headers that hide or reveal additional content when selected.

Passed WCAG 2.1 AA

Borderless

Congress shall make no law respecting an establishment of religion, or prohibiting the free exercise thereof; or abridging the freedom of speech, or of the press; or the right of the people peaceably to assemble, and to petition the Government for a redress of grievances.

A well regulated Militia, being necessary to the security of a free State, the right of the people to keep and bear Arms, shall not be infringed.

  • This is a list item
  • Another list item

No Soldier shall, in time of peace be quartered in any house, without the consent of the Owner, nor in time of war, but in a manner to be prescribed by law.

The right of the people to be secure in their persons, houses, papers, and effects, against unreasonable searches and seizures, shall not be violated, and no Warrants shall issue, but upon probable cause, supported by Oath or affirmation, and particularly describing the place to be searched, and the persons or things to be seized.

No person shall be held to answer for a capital, or otherwise infamous crime, unless on a presentment or indictment of a Grand Jury, except in cases arising in the land or naval forces, or in the Militia, when in actual service in time of War or public danger; nor shall any person be subject for the same offence to be twice put in jeopardy of life or limb; nor shall be compelled in any criminal case to be a witness against himself, nor be deprived of life, liberty, or property, without due process of law; nor shall private property be taken for public use, without just compensation.

Bordered

Congress shall make no law respecting an establishment of religion, or prohibiting the free exercise thereof; or abridging the freedom of speech, or of the press; or the right of the people peaceably to assemble, and to petition the Government for a redress of grievances.

A well regulated Militia, being necessary to the security of a free State, the right of the people to keep and bear Arms, shall not be infringed.

  • This is a list item
  • Another list item

No Soldier shall, in time of peace be quartered in any house, without the consent of the Owner, nor in time of war, but in a manner to be prescribed by law.

The right of the people to be secure in their persons, houses, papers, and effects, against unreasonable searches and seizures, shall not be violated, and no Warrants shall issue, but upon probable cause, supported by Oath or affirmation, and particularly describing the place to be searched, and the persons or things to be seized.

No person shall be held to answer for a capital, or otherwise infamous crime, unless on a presentment or indictment of a Grand Jury, except in cases arising in the land or naval forces, or in the Militia, when in actual service in time of War or public danger; nor shall any person be subject for the same offence to be twice put in jeopardy of life or limb; nor shall be compelled in any criminal case to be a witness against himself, nor be deprived of life, liberty, or property, without due process of law; nor shall private property be taken for public use, without just compensation.

Multiselectable

Congress shall make no law respecting an establishment of religion, or prohibiting the free exercise thereof; or abridging the freedom of speech, or of the press; or the right of the people peaceably to assemble, and to petition the Government for a redress of grievances.

A well regulated Militia, being necessary to the security of a free State, the right of the people to keep and bear Arms, shall not be infringed.

  • This is a list item
  • Another list item

No Soldier shall, in time of peace be quartered in any house, without the consent of the Owner, nor in time of war, but in a manner to be prescribed by law.

The right of the people to be secure in their persons, houses, papers, and effects, against unreasonable searches and seizures, shall not be violated, and no Warrants shall issue, but upon probable cause, supported by Oath or affirmation, and particularly describing the place to be searched, and the persons or things to be seized.

No person shall be held to answer for a capital, or otherwise infamous crime, unless on a presentment or indictment of a Grand Jury, except in cases arising in the land or naval forces, or in the Militia, when in actual service in time of War or public danger; nor shall any person be subject for the same offence to be twice put in jeopardy of life or limb; nor shall be compelled in any criminal case to be a witness against himself, nor be deprived of life, liberty, or property, without due process of law; nor shall private property be taken for public use, without just compensation. 

<h3 class="site-preview-heading">Borderless</h3>
<div class="usa-accordion">
  <h4 class="usa-accordion__heading">
    <button
      type="button"
      class="usa-accordion__button"
      aria-expanded="true"
      aria-controls="a1"
    >
      First Amendment
    </button>
  </h4>
  <div id="a1" class="usa-accordion__content usa-prose">
    <p>
      Congress shall make no law respecting an establishment of religion, or
      prohibiting the free exercise thereof; or abridging the freedom of speech,
      or of the press; or the right of the people peaceably to assemble, and to
      petition the Government for a redress of grievances.
    </p>
  </div>
  <h4 class="usa-accordion__heading">
    <button
      type="button"
      class="usa-accordion__button"
      aria-expanded="false"
      aria-controls="a2"
    >
      Second Amendment
    </button>
  </h4>
  <div id="a2" class="usa-accordion__content usa-prose">
    <p>
      A well regulated Militia, being necessary to the security of a free State,
      the right of the people to keep and bear Arms, shall not be infringed.
    </p>
    <ul>
      <li>This is a list item</li>
      <li>Another list item</li>
    </ul>
  </div>
  <h4 class="usa-accordion__heading">
    <button
      type="button"
      class="usa-accordion__button"
      aria-expanded="false"
      aria-controls="a3"
    >
      Third Amendment
    </button>
  </h4>
  <div id="a3" class="usa-accordion__content usa-prose">
    <p>
      No Soldier shall, in time of peace be quartered in any house, without the
      consent of the Owner, nor in time of war, but in a manner to be prescribed
      by law.
    </p>
  </div>
  <h4 class="usa-accordion__heading">
    <button
      type="button"
      class="usa-accordion__button"
      aria-expanded="false"
      aria-controls="a4"
    >
      Fourth Amendment
    </button>
  </h4>
  <div id="a4" class="usa-accordion__content usa-prose">
    <p>
      The right of the people to be secure in their persons, houses, papers, and
      effects, against unreasonable searches and seizures, shall not be
      violated, and no Warrants shall issue, but upon probable cause, supported
      by Oath or affirmation, and particularly describing the place to be
      searched, and the persons or things to be seized.
    </p>
  </div>
  <h4 class="usa-accordion__heading">
    <button
      type="button"
      class="usa-accordion__button"
      aria-expanded="false"
      aria-controls="a5"
    >
      Fifth Amendment
    </button>
  </h4>
  <div id="a5" class="usa-accordion__content usa-prose">
    <p>
      No person shall be held to answer for a capital, or otherwise infamous
      crime, unless on a presentment or indictment of a Grand Jury, except in
      cases arising in the land or naval forces, or in the Militia, when in
      actual service in time of War or public danger; nor shall any person be
      subject for the same offence to be twice put in jeopardy of life or limb;
      nor shall be compelled in any criminal case to be a witness against
      himself, nor be deprived of life, liberty, or property, without due
      process of law; nor shall private property be taken for public use,
      without just compensation.
    </p>
  </div>
</div>

<h3 class="site-preview-heading">Bordered</h3>

<div class="usa-accordion usa-accordion--bordered">
  <h4 class="usa-accordion__heading">
    <button
      type="button"
      class="usa-accordion__button"
      aria-expanded="true"
      aria-controls="b-a1"
    >
      First Amendment
    </button>
  </h4>
  <div id="b-a1" class="usa-accordion__content usa-prose">
    <p>
      Congress shall make no law respecting an establishment of religion, or
      prohibiting the free exercise thereof; or abridging the freedom of speech,
      or of the press; or the right of the people peaceably to assemble, and to
      petition the Government for a redress of grievances.
    </p>
  </div>
  <h4 class="usa-accordion__heading">
    <button
      type="button"
      class="usa-accordion__button"
      aria-expanded="false"
      aria-controls="b-a2"
    >
      Second Amendment
    </button>
  </h4>
  <div id="b-a2" class="usa-accordion__content usa-prose">
    <p>
      A well regulated Militia, being necessary to the security of a free State,
      the right of the people to keep and bear Arms, shall not be infringed.
    </p>
    <ul>
      <li>This is a list item</li>
      <li>Another list item</li>
    </ul>
  </div>
  <h4 class="usa-accordion__heading">
    <button
      type="button"
      class="usa-accordion__button"
      aria-expanded="false"
      aria-controls="b-a3"
    >
      Third Amendment
    </button>
  </h4>
  <div id="b-a3" class="usa-accordion__content usa-prose">
    <p>
      No Soldier shall, in time of peace be quartered in any house, without the
      consent of the Owner, nor in time of war, but in a manner to be prescribed
      by law.
    </p>
  </div>
  <h4 class="usa-accordion__heading">
    <button
      type="button"
      class="usa-accordion__button"
      aria-expanded="false"
      aria-controls="b-a4"
    >
      Fourth Amendment
    </button>
  </h4>
  <div id="b-a4" class="usa-accordion__content usa-prose">
    <p>
      The right of the people to be secure in their persons, houses, papers, and
      effects, against unreasonable searches and seizures, shall not be
      violated, and no Warrants shall issue, but upon probable cause, supported
      by Oath or affirmation, and particularly describing the place to be
      searched, and the persons or things to be seized.
    </p>
  </div>
  <h4 class="usa-accordion__heading">
    <button
      type="button"
      class="usa-accordion__button"
      aria-expanded="false"
      aria-controls="b-a5"
    >
      Fifth Amendment
    </button>
  </h4>
  <div id="b-a5" class="usa-accordion__content usa-prose">
    <p>
      No person shall be held to answer for a capital, or otherwise infamous
      crime, unless on a presentment or indictment of a Grand Jury, except in
      cases arising in the land or naval forces, or in the Militia, when in
      actual service in time of War or public danger; nor shall any person be
      subject for the same offence to be twice put in jeopardy of life or limb;
      nor shall be compelled in any criminal case to be a witness against
      himself, nor be deprived of life, liberty, or property, without due
      process of law; nor shall private property be taken for public use,
      without just compensation.
    </p>
  </div>
</div>

<h3 class="site-preview-heading">Multiselectable</h3>

<div class="usa-accordion usa-accordion--multiselectable" data-allow-multiple>
  <h4 class="usa-accordion__heading">
    <button
      type="button"
      class="usa-accordion__button"
      aria-expanded="true"
      aria-controls="m-a1"
    >
      First Amendment
    </button>
  </h4>
  <div id="m-a1" class="usa-accordion__content usa-prose">
    <p>
      Congress shall make no law respecting an establishment of religion, or
      prohibiting the free exercise thereof; or abridging the freedom of speech,
      or of the press; or the right of the people peaceably to assemble, and to
      petition the Government for a redress of grievances.
    </p>
  </div>
  <h4 class="usa-accordion__heading">
    <button
      type="button"
      class="usa-accordion__button"
      aria-expanded="false"
      aria-controls="m-a2"
    >
      Second Amendment
    </button>
  </h4>
  <div id="m-a2" class="usa-accordion__content usa-prose">
    <p>
      A well regulated Militia, being necessary to the security of a free State,
      the right of the people to keep and bear Arms, shall not be infringed.
    </p>
    <ul>
      <li>This is a list item</li>
      <li>Another list item</li>
    </ul>
  </div>
  <h4 class="usa-accordion__heading">
    <button
      type="button"
      class="usa-accordion__button"
      aria-expanded="false"
      aria-controls="m-a3"
    >
      Third Amendment
    </button>
  </h4>
  <div id="m-a3" class="usa-accordion__content usa-prose">
    <p>
      No Soldier shall, in time of peace be quartered in any house, without the
      consent of the Owner, nor in time of war, but in a manner to be prescribed
      by law.
    </p>
  </div>
  <h4 class="usa-accordion__heading">
    <button
      type="button"
      class="usa-accordion__button"
      aria-expanded="false"
      aria-controls="m-a4"
    >
      Fourth Amendment
    </button>
  </h4>
  <div id="m-a4" class="usa-accordion__content usa-prose">
    <p>
      The right of the people to be secure in their persons, houses, papers, and
      effects, against unreasonable searches and seizures, shall not be
      violated, and no Warrants shall issue, but upon probable cause, supported
      by Oath or affirmation, and particularly describing the place to be
      searched, and the persons or things to be seized.
    </p>
  </div>
  <h4 class="usa-accordion__heading">
    <button
      type="button"
      class="usa-accordion__button"
      aria-expanded="false"
      aria-controls="m-a5"
    >
      Fifth Amendment
    </button>
  </h4>
  <div id="m-a5" class="usa-accordion__content usa-prose">
    <p>
      No person shall be held to answer for a capital, or otherwise infamous
      crime, unless on a presentment or indictment of a Grand Jury, except in
      cases arising in the land or naval forces, or in the Militia, when in
      actual service in time of War or public danger; nor shall any person be
      subject for the same offence to be twice put in jeopardy of life or limb;
      nor shall be compelled in any criminal case to be a witness against
      himself, nor be deprived of life, liberty, or property, without due
      process of law; nor shall private property be taken for public use,
      without just compensation.
    </p>
  </div>
</div>

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 guidance

Test the accordion component in your own project.

USWDS tested the accordion component for accessibility. You should test your implementation, too.

Use accordion accessibility tests
  • Code header areas in the accordion as buttons. Using a <button type="button"> assures accordions are usable with both screen readers and keyboards.
  • Use meaningful expansion button labels. Aim for informative labels like “Explore federal compliance checklists” rather than vague ones like “Click here.”
  • Use aria-controls to associate an accordion button with its related content. Connect an accordion button control with its appropriate content region by referencing the controlled element’s id in the button’s aria-controls attribute.
  • 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.
  • You do not need to add text alternatives for the collapsed and expanded accordion states. These states are set programmatically with JavaScript.

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. When the accordion is initialized, the JavaScript will automatically add aria-expanded="false" attribute to all other accordion buttons.

Accordion settings

Variable Description
$theme-accordion-background-color

Background color of the accordion content.
$theme-accordion-border-width

Border width of the bordered accordion.
$theme-accordion-border-color

Border color of the bordered accordion.
$theme-accordion-button-background-color

Background color of the accordion button.
$theme-accordion-font-family

Font family of the accordion.

Accordion variants

Variant Description

.usa-accordion--bordered

Display a border around accordion content.

Accessibility test status

The USWDS team did 23 tests based on WCAG 2.1 AA success criteria.

Overview of recent accessibility test results:
Total tests
Passed
Passed with exceptions
Conditional
Failed
23 21 0 2 0

Overview of recent accessibility test results:

  • Passed: 21
  • Passed with exceptions: 0
  • Conditional: 2
  • Failed: 0

Learn more on the accordion accessibility tests page.

Package

  • Package usage: @forward "usa-accordion";
  • Dependencies: uswds-fonts, usa-icon

Latest updates

Meaningful code and guidance updates are listed in the following table:

Date USWDS version Affects Breaking Description
2024-01-17 N/A
  • Guidance
 No

Added WCAG compliance tag and accessibility test status section. More information: uswds-site#2138

2023-11-20 N/A
  • Guidance
 No

Added usa-icon to the dependency list and removed usa-list. More information: uswds-site#2149

2023-06-09 3.5.0
  • Styles
  • Settings
 No

Added two new settings to customize accordion background colors. You can now customize accordion button and content background colors with $theme-accordion-button-background-color and $theme-accordion-background-color. More information: uswds#5269

2023-06-09 3.5.0
  • Accessibility
  • Styles
 No

Adjusted forced colors mode styles to ensure visibility and increase consistency. Forced colors mode styles will now override the background color and display the button outline. The open/close icons now dynamically adjust to ButtonText colors. More information: uswds#5286

2022-08-05 3.1.0
  • JavaScript
  • Markup
 Breaking

Breaking Added type="button" to all non-form buttons to prevent default submit behaviors. This allowed us to remove preventDefault() from the relevant component JavaScript. More information: uswds#4695

2022-08-01 N/A
  • Guidance
 No

Updated documentation to reference the correct multi-select attribute. The attribute was updated from aria-multiselectable="true" to data-allow-multiple. More information: uswds-site#1718

2022-04-28 3.0.0
  • Assets
  • JavaScript
  • Styles
 Breaking

Breaking Updated to Sass module syntax and new package structure. More information: uswds#4656

2021-03-17 2.11.1
  • Assets
 No

Restored missing white icons. Restored add--white and remove--white icons. More information: uswds#4106

2021-03-02 2.10.2
  • Assets
 No

Introduced white add, remove, and expand_more icons. More information: uswds#4061