Black Lives Matter. Support the Equal Justice Initiative.
Skip to main contentCarbon Design System

Accordion

How it works

The accordion Carbon component provides a vertically stacked layout for web content, commonly used to reduce scrolling. The accordion header is a button that is used to expand and collapse each accordion panel. Buttons are used so that the accordions are tab-able by keyboard users and accessible to screen readers. Tab and Shift-Tab are used to navigate through each accordion header and all focusable elements in the accordion should be included in the page Tab sequence. Enter or Space expand and collapse each accordion panel.

When an accordion panel is collapsed the content is hidden, therefore the ARIA state aria-expanded="false" advises users of assistive technologies that the accordion panel is not visible. When the accordion header is expanded the ARIA state changes to aria-expanded="true" and the accordion panel content is displayed. Each accordion header contains an ARIA label, and the header buttons have an ARIA-control property set that points to the unique id of the panel it controls. When focus is on the accordion header there is a prominent style change to the border as well as background of the accordion header.

Accessibility considerations

This component has been validated to meet the WCAG 2.0 AA and Section 508 accessibility guidelines, however changes made by the content owner can affect accessibility compliance. Be sure to review and follow the guidance in this section when updating or adding new content to this component.

  1. Each accordion header must have a unique title (implemented via the label for the button) that clearly describes the accordion panel content. This is particularly helpful for users of assistive technologies so they have the necessary information to efficiently navigate the content without having to expand every section.
  2. Carbon components should be used to create the content that displays within each accordion panel.
  3. Avoid keyboard traps when adding components to the accordion panel. For example, the user expands an accordion, but is unable to tab to the next focusable element.
  4. Although the accordion component passes accessibility testing, content authors need to ensure the content that is added to the accordion is accessible. For example, if you add an image to the accordion header or panel you need to include alternative text to pass accessibility testing.

Resources

Accessibility testing

Accessibility issues are tracked in the Carbon Component GitHub repository.

Automated test

Automated test environment
Results
- macOS Mojave version 10.14.2 with VoiceOver
- Chrome version 77.0.3865.90
- Dynamic Assessment Plugin (DAP) version 1.8.0.0 - IBM Accessibility WCAG 2.1 Sept. 2019 Ruleset
- Carbon React version 7.7.1
DAP test:
- Violations

macOS screen reader tests

Environment
Results
- macOS Mojave version 10.14.6 with VoiceOver
- Chrome version 77.0.3865.90
- Carbon React version 7.7.1
VoiceOver(VO) Test:
  1. The Tab key and Shift-Tab navigate between accordion headers. VO announces, expand/collapse, title, collapsed, button, the button's state (expanded or collapsed), list, 1 item. You are currently on a button...
  2. Press Control-Option-Space (or Space) to expand or collapse the accordion panel. VO announces expand/collapse title, the button's state (expanded or collapsed).
  3. With the second or third accordion header expanded, Press Control-Option-Right Arrow. VO announces, the accordion panel content and the line number in the list.
  4. Press Control-Option-Left Arrow - VO announces reads the accordion header again.
- macOS Mojave version 10.14.6 with VoiceOver
- Safari version 13.0.2
- Carbon React version 7.7.1
VoiceOver(VO) test:
  1. The Tab key and Shift-Tab navigate between accordion headers. VO announces, expand/collapse, title, collapsed, button, the button's state (expanded or collapsed), group.
  2. Press Control-Option-Space (or Space) to expand or collapse the accordion panel. VO announces expand/collapse title, the button's state (expanded or collapsed).
  3. With the second or third accordion header expanded, Press Control-Option-Right Arrow. VO announces, the accordion panel content and the line number in the list. Your are currently on a text area.
  4. Press Control-Option-Left Arrow - VO announces reads the accordion header again.

Windows screen reader tests

Environment
Results
- Microsoft Windows 10
- JAWS 19.1903.47
- Firefox version 67
- Carbon React version 7.7.1
JAWS test:
  1. The Tab key and Shift-Tab navigate between accordion headers. JAWS announces, title, and expand/collapse status.
  2. Press the Enter or Space key on the title. JAWS announces expand or collapsed.
  3. Navigate the text using the Up and Down Arrow keys, when JAWS read the headers and associated text if expanded in a linear order.
  4. Please note that sometimes it takes a second for the text to update after a title is expanded. When pressing the down arrow key immediately after JAWS announces "expanded", JAWS jumps past the text and reads the next title.
- Microsoft Windows 10
- JAWS 19.1903.47
- Chrome version 71.0.3578.98 (Official Build) (64-bit)
- Carbon React version 7.7.1
JAWS test:
  1. The Tab key and Shift-Tab navigate between accordion headers. JAWS announces, title, and expand/collapse status.
  2. Press the Enter or Space key on the title. JAWS announces expand or collapsed.
  3. Navigate the text using the Up and Down Arrow keys, when JAWS read the headers and associated text if expanded in a linear order.
  4. Please note that sometimes it takes a second for the text to update after a title is expanded. When pressing the down arrow key immediately after JAWS announces "expanded", JAWS jumps past the text and reads the next title.
- Microsoft Windows 10
- NVDA version 2018.4.1
- Chrome version 72.0.3626.96 (Official Build) (64-bit)
- Carbon React version 7.7.1
NVDA test:
  1. The Tab key and Shift-Tab navigate between accordion headers. NVDA announces, title, and expand/collapse status.
  2. Press the Enter or Space key on the title. NVDA announces expand or collapsed.
  3. Navigate the text using the Up and Down Arrow keys, when JAWS read the headers and associated text if expanded in a linear order.

iOS screen reader tests

Environment
Results
- iOS version 13.1.3 with VoiceOver
- Safari version 13.1.3
- Carbon React version 7.7.1
VoiceOver test:
  1. To navigate the accordion, swipe left or right, or use the Left or Right Arrow keys when quick nav mode is on. On each header, VoiceOver announces the header, and expanded/collapsed status.
  2. To expand or collapse the accordion, doubletap on the header, or press Control+Option+Space. VoiceOver announces, exapnaded or collapses.
  3. In some cases, VoiceOver also reads out the entire header, it seems to happen randomly, possibly have to do with the speed of the phone.
  4. Navigate the text by swiping left or right, or by pressing the Left or Right Arrow keys when quick navigation mode is on. After each title, when moving to the left or right, VoiceOver will read the text if it is expanded.

Android screen reader tests

Environment
Results
- Android version 9 with Talkback
- Chrome version 72.0.3626.96 (Official Build) (64-bit)
- Carbon React version 7.7.1
Talkback test:
  1. To navigate the accordion, swipe left or right, or use the Alt+Left or Right Arrow keys. On each header, TalkBack announces the header, and expanded/collapsed status.
  2. To expand or collapse the accordion, doubletap on the header, or press Alt+Enter. Talkback announces expanded or collapses.
  3. Navigate the text by swiping left or right, or by pressing the Left or Right Arrow keys. After each title, when moving to the left or right, Talkback will read the text if it is expanded.
Edit this page on GitHub
Previous
Accordion: Code
Next
Components: Breadcrumb