Accordion

An accordion helps me scan long pages by letting me show or hide sections of text.

The Accordion component allows users to find information on a page by clicking headings to expand or hide content beneath. They are always used to collapse multiple heading groups and are most useful for fitting long-form content into a limited space.

Details

Extends: USWDS Accordion component
Honeycrisp: Accordion molecule
Customization: Design tokens and Styles
Modifier: .cfa-accordion .usa-accordion--bordered

The Accordion extends the USWDS Accordion component. The visual appearance is modified using design tokens applied to the USWDS Accordion component settings from the Honeycrisp Accordion molecule. Further customization is applied using the CSS modifier(s) .cfa-accordion .usa-accordion--bordered to add styles defined in a custom stylesheet.

Design tokens. Tokens define the name of basic system elements such as color, typography, or spacing. The values of tokens are relative to how the system defines them. This enables teams to alter the visual appearance of components yet remain within the system boundaries. Learn more about tokens on the Bixal's Design Tokens Guide.

Modifier. A modifier is a class name that applies a variant, type, or extended style customization to modify the component's visual appearance.

Examples

Bordered

Personal information
People who live with you
Income
Expenses
Assets

Learn more about how we protect your personal information.

If you are applying for food assistance (SNAP), you will have the choice to submit an incomplete application with only your name, address, and signature.

By choosing to submit an incomplete application, you may experience longer processing time and more communication with your county.

At the end of this application, you will have the option to add documents, like pay stubs, rent receipts, or medical bills.

You can use your phone to take photos of paper documents or select photos from your device.

You can always return to our homepage to add documents later, too.

Your application submission date is the earliest date your benefits can begin.

Most programs on this application, including food and cash assistance, require an interview after you submit. Look for a letter in the mail or a phone call from your county.

View HTML

The HTML for the demonstration above is rendered using context passed to the component's Thymeleaf template fragment. Learn how to include component templates for Thymeleaf and Ruby in the source and usage section.

<div class="usa-accordion cfa-accordion usa-accordion--bordered" data-allow-multiple="true">
  <h3 class="usa-accordion__heading">
    <button type="button" class="usa-accordion__button" aria-expanded="true" aria-controls="aria-c-abe0d57a84caf">We'll ask you about</button>
  </h3>
  <div class="usa-accordion__content" id="aria-c-abe0d57a84caf">
    <ul>
      <li>Personal information</li>
      <li>People who live with you</li>
      <li>Income</li>
      <li>Expenses</li>
      <li>Assets</li>
    </ul>
    <p>
      <a href="#">Learn more about how we protect your personal information</a>.
    </p>
  </div>
  <h3 class="usa-accordion__heading">
    <button type="button" class="usa-accordion__button" aria-expanded="false" aria-controls="aria-c-4660b22b10ae6">Submitting an incomplete application (SNAP only)</button>
  </h3>
  <div class="usa-accordion__content" id="aria-c-4660b22b10ae6">
    <p>If you are applying for food assistance (SNAP), you will have the choice to submit an incomplete application with only your name, address, and signature.</p>
    <p>By choosing to submit an incomplete application, you may experience longer processing time and more communication with your county.</p>
  </div>
  <h3 class="usa-accordion__heading">
    <button type="button" class="usa-accordion__button" aria-expanded="false" aria-controls="aria-c-282dd58b5b881">Adding documents</button>
  </h3>
  <div class="usa-accordion__content" id="aria-c-282dd58b5b881">
    <p>At the end of this application, you will have the option to add documents, like pay stubs, rent receipts, or medical bills.</p>
    <p>You can use your phone to take photos of paper documents or select photos from your device.</p>
    <p>You can always return to our homepage to add documents later, too.</p>
  </div>
  <h3 class="usa-accordion__heading">
    <button type="button" class="usa-accordion__button" aria-expanded="false" aria-controls="aria-c-72e85a394a156">After you submit</button>
  </h3>
  <div class="usa-accordion__content" id="aria-c-72e85a394a156">
    <p>Your application submission date is the earliest date your benefits can begin.</p>
    <p>Most programs on this application, including food and cash assistance, require an interview after you submit. Look for a letter in the mail or a phone call from your county.</p>
  </div>
</div>

<div class="usa-accordion cfa-accordion usa-accordion--bordered" data-allow-multiple="true">
  <h3 class="usa-accordion__heading">
    <button type="button" class="usa-accordion__button" aria-expanded="true" aria-controls="aria-c-abe0d57a84caf">We'll ask you about</button>
  </h3>
  <div class="usa-accordion__content" id="aria-c-abe0d57a84caf">
    <ul>
      <li>Personal information</li>
      <li>People who live with you</li>
      <li>Income</li>
      <li>Expenses</li>
      <li>Assets</li>
    </ul>
    <p>
      <a href="#">Learn more about how we protect your personal information</a>.
    </p>
  </div>
  <h3 class="usa-accordion__heading">
    <button type="button" class="usa-accordion__button" aria-expanded="false" aria-controls="aria-c-4660b22b10ae6">Submitting an incomplete application (SNAP only)</button>
  </h3>
  <div class="usa-accordion__content" id="aria-c-4660b22b10ae6">
    <p>If you are applying for food assistance (SNAP), you will have the choice to submit an incomplete application with only your name, address, and signature.</p>
    <p>By choosing to submit an incomplete application, you may experience longer processing time and more communication with your county.</p>
  </div>
  <h3 class="usa-accordion__heading">
    <button type="button" class="usa-accordion__button" aria-expanded="false" aria-controls="aria-c-282dd58b5b881">Adding documents</button>
  </h3>
  <div class="usa-accordion__content" id="aria-c-282dd58b5b881">
    <p>At the end of this application, you will have the option to add documents, like pay stubs, rent receipts, or medical bills.</p>
    <p>You can use your phone to take photos of paper documents or select photos from your device.</p>
    <p>You can always return to our homepage to add documents later, too.</p>
  </div>
  <h3 class="usa-accordion__heading">
    <button type="button" class="usa-accordion__button" aria-expanded="false" aria-controls="aria-c-72e85a394a156">After you submit</button>
  </h3>
  <div class="usa-accordion__content" id="aria-c-72e85a394a156">
    <p>Your application submission date is the earliest date your benefits can begin.</p>
    <p>Most programs on this application, including food and cash assistance, require an interview after you submit. Look for a letter in the mail or a phone call from your county.</p>
  </div>
</div>

View context passed to this component

Context is the information necessary to configure and render a component template to HTML. It may include plain text strings, HTML, class names, IDs or other HTML attribute values. The context here is defined as JSON but the root attributes are translated to different variable syntaxes for Thymeleaf and Ruby templates. Learn how to pass these variables to each component template in the source and usage section.

{
  "modifier": "cfa-accordion usa-accordion--bordered",
  "multiple": true,
  "items": [
    {
      "expanded": true,
      "controls": "aria-c-abe0d57a84caf",
      "heading": "We'll ask you about",
      "body": "<ul><li>Personal information</li><li>People who live with you</li><li>Income</li><li>Expenses</li><li>Assets</li></ul><p><a href=\"#\">Learn more about how we protect your personal information</a>.</p>"
    },
    {
      "expanded": false,
      "controls": "aria-c-4660b22b10ae6",
      "heading": "Submitting an incomplete application (SNAP only)",
      "body": "<p>If you are applying for food assistance (SNAP), you will have the choice to submit an incomplete application with only your name, address, and signature.</p><p>By choosing to submit an incomplete application, you may experience longer processing time and more communication with your county.</p>"
    },
    {
      "expanded": false,
      "controls": "aria-c-282dd58b5b881",
      "heading": "Adding documents",
      "body": "<p>At the end of this application, you will have the option to add documents, like pay stubs, rent receipts, or medical bills.</p><p>You can use your phone to take photos of paper documents or select photos from your device.</p><p>You can always return to our homepage to add documents later, too.</p>"
    },
    {
      "expanded": false,
      "controls": "aria-c-72e85a394a156",
      "heading": "After you submit",
      "body": "<p>Your application submission date is the earliest date your benefits can begin.</p><p>Most programs on this application, including food and cash assistance, require an interview after you submit. Look for a letter in the mail or a phone call from your county.</p>"
    }
  ]
}

{
  "modifier": "cfa-accordion usa-accordion--bordered",
  "multiple": true,
  "items": [
    {
      "expanded": true,
      "controls": "aria-c-abe0d57a84caf",
      "heading": "We'll ask you about",
      "body": "<ul><li>Personal information</li><li>People who live with you</li><li>Income</li><li>Expenses</li><li>Assets</li></ul><p><a href=\"#\">Learn more about how we protect your personal information</a>.</p>"
    },
    {
      "expanded": false,
      "controls": "aria-c-4660b22b10ae6",
      "heading": "Submitting an incomplete application (SNAP only)",
      "body": "<p>If you are applying for food assistance (SNAP), you will have the choice to submit an incomplete application with only your name, address, and signature.</p><p>By choosing to submit an incomplete application, you may experience longer processing time and more communication with your county.</p>"
    },
    {
      "expanded": false,
      "controls": "aria-c-282dd58b5b881",
      "heading": "Adding documents",
      "body": "<p>At the end of this application, you will have the option to add documents, like pay stubs, rent receipts, or medical bills.</p><p>You can use your phone to take photos of paper documents or select photos from your device.</p><p>You can always return to our homepage to add documents later, too.</p>"
    },
    {
      "expanded": false,
      "controls": "aria-c-72e85a394a156",
      "heading": "After you submit",
      "body": "<p>Your application submission date is the earliest date your benefits can begin.</p><p>Most programs on this application, including food and cash assistance, require an interview after you submit. Look for a letter in the mail or a phone call from your county.</p>"
    }
  ]
}

Guidance

Heading order. It is a best practice to ensure the accordion heading level does not skip and is in order with other page headings. However, this does not contribute to accessible success criteria.

Refer to additional guidance on the USWDS documentation site.

USWDS documentation site

Additional references

Heading levels should only increase by one | dequeuniversity.com

Accessibility

Customization to the visual appearance of the Accordion has been verified for WCAG 2.1 AA contrast minimum success.
The Accordion examples pass manual audits (WCAG 2.1 AA using axe or Lighthouse).
The Accordion achieves WCAG 2.1 AA resizing success.
Resizing text up to 200% without loss of content or functionality.
The Accordion passes keyboard interaction tests.
No keyboard test has been created.
The Accordion passes screen reader interaction tests.
No screen reader test has been created.
Guidance on ensuring Accordion accessibility has been provided in this documentation.

Refer to additional accessibility guidance on the USWDS documentation site.

Checklist Key

Passes
Unchecked

Design library component

Source and usage

Package: @codeforamerica/uswds/packages/cfa-accordion

Sass stylesheet: ./_cfa-accordion.scss
Thymeleaf template fragment: ./cfa-accordion.th.html
Embedded Ruby (ERB) partial template: ./_cfa-accordion.html.erb
JavaScript enables the expanding and collapsing of accordion sections as well as toggles ARIA attributes on the button and target region. Guidance on individual module loading will added. Currently, there is one script that imports all modules. The source is located at @codeforamerica/js/index.js. This entrypoint is compiled using Rollup.js and distributed to @codeforamerica/dist/js/default.js.

Packages are collections of functionality that make up a component. Typically, they include stylesheets, templates, and scripts. Learn more about packages on the USWDS documentation site.

Sass theme settings

Below is a demonstration of customizing the component theme settings. Refer to the theme and package-level settings documentation.

// Theme-level settings
@use 'cfa-uswds-theme' with (
  // Global theme settings that affect the component, changing these will affect other components
  $cfa-color-base-lightest: 'gray-warm-4', // Affects accordion background
  $cfa-color-base-lighter: 'gray-warm-10', // Affects accordion button hover state
  // Component specific settings
  $cfa-accordion-border-width: 2px,
  $cfa-accordion-border-color: 'gray-warm-20'
);

USWDS theme settings

Refer to the usage documentation for additional USWDS theme settings.

@use "uswds-core" with ( /* additional USWDS theme settings */ );

Thymeleaf template fragment

This is the pre-rendered template fragment from the package. It is the same template used to render the demonstrations above. You may copy and paste from this example or use the template using the th:block th:replace tag. See the example below.

<div th:fragment="accordion(modifier, multiple, items)" class="usa-accordion" th:classappend="${modifier}" th:attr="data-allow-multiple=${multiple}">
  <th:block th:each="item: ${items}">
    <h3 class="usa-accordion__heading">
      <button type="button" class="usa-accordion__button" th:attr="aria-expanded=${item.expanded},aria-controls=${item.controls}" th:text="${item.heading}">Heading</button>
    </h3>
    <div th:if="${item.body}" th:attr="id=${item.controls}" class="usa-accordion__content" th:utext="${item.body}"></div>
    <div th:if="${item.text}" th:attr="id=${item.controls}" class="usa-accordion__content">
      <p th:text="${item.text}">Text</p>
    </div>
  </th:block>
</div>

Template fragment inclusion

Below is an example of how to use the fragment from the package directory using the th:block th:replace inclusion tag. Replace the fragment parameters using your variables or context.

<th:block th:replace="~{packages/cfa-accordion/cfa-accordion.th :: accordion(${modifier}, ${multiple}, ${items})}" />

ERB template partial

This is the pre-rendered partial template from the package. You may copy and paste from this example or use the template directly from the path.

<div class="usa-accordion<% if defined?(modifier) %> <%= modifier %><% end %>"<% if defined?(multiple) %> data-allow-multiple<% end %>>
  <% items.each do |item| %>
    <h3 class="usa-accordion__heading">
      <button type="button" class="usa-accordion__button"<% if item['expanded'] %> aria-expanded="<%= item['expanded'] %>"<% end %><% if item['controls'] %> aria-controls="<%= item['controls'] %>"<% end %>>
        <%= item['heading'] %>
      </button>
    </h3>
    <div class="usa-accordion__content"<% if item['controls'] %> id="<%= item['controls'] %>"<% end %>>
      <% if item['body'] %>
        <%= item['body'] %>
      <% elsif item['text'] %>
        <p><%= item['text'] %></p>
      <% end %>
    </div>
  <% end %>
</div>

Partial render

Below is an example of how to include the partial in a view from the package directory using the Ruby ERB class. Replace the argument values using your variables or context. In a Rails environment, the render method can be used instead with the same hash values.

<%= ERB.new(File.read('packages/cfa-accordion/_cfa-accordion.html.erb'), 0, 0, '@accordion').result_with_hash({modifier: modifier, multiple: multiple, items: items}) %>

Have a suggestion or need help?