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 key and Shift-Tab keys are used to navigate through each accordion header and all focusable elements in the accordion should be included in the page Tab sequence. The Enter or Space key expand and collapse each accordion panel.
WAI-ARIA roles and states are used to ensure the component is accessible to people using assistive technologies. The accordion component is assigned the ARIA role="presentation" because it is used to layout web content. When an accordion panel is collapsed the content is hidden so 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 a 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.
- 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.
- Carbon components should be used to create the content that displays within each accordion panel.
- 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.
- 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
- W3C WAI-ARIA Authoring Practices Accordion Design Pattern covers the usage of ARIA names, state and roles, as well as the expected keyboard interactions.
- IBM Accessibility Checklist Checkpoint:
- 1.3.1 Info and Relationships (WCAG Success Criteria 1.3.1)
- 1.3.2 Meaningful Sequence (WCAG Success Criteria 1.3.2)
- 2.1.1 Keyboard (WCAG Success Criteria 2.1.1)
- 2.1.2 No Keyboard Trap (WCAG Success Criteria 2.1.2)
- 2.4.3 Focus Order (WCAG Success Criteria 2.4.3)
- 2.4.6 Headings and Labels (WCAG Success Criteria 2.4.6)
- 2.4.7 Focus Visible (WCAG Success Criteria 2.4.7)
- 4.1.2 Name, Role, Value (WCAG Success Criteria 4.1.2)
Accessibility testing
Accessibility issues are tracked in the Carbon Component GitHub repository.
Automated test
- 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
- Violations
macOS screen reader tests
- Chrome version 77.0.3865.90
- Carbon React version 7.7.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...
- 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).
- 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.
- Press Control-Option-Left Arrow - VO announces reads the accordion header again.
- Safari version 13.0.2
- Carbon React version 7.7.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.
- 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).
- 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.
- Press Control-Option-Left Arrow - VO announces reads the accordion header again.
Windows screen reader tests
- JAWS 19.1903.47
- Firefox version 67
- Carbon React version 7.7.1
- The Tab key and Shift-Tab navigate between accordion headers. JAWS announces, title, and expand/collapse status.
- Press the Enter or Space key on the title. JAWS announces expand or collapsed.
- Navigate the text using the Up and Down Arrow keys, when JAWS read the headers and associated text if expanded in a linear order.
- 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.
- JAWS 19.1903.47
- Chrome version 71.0.3578.98 (Official Build) (64-bit)
- Carbon React version 7.7.1
- The Tab key and Shift-Tab navigate between accordion headers. JAWS announces, title, and expand/collapse status.
- Press the Enter or Space key on the title. JAWS announces expand or collapsed.
- Navigate the text using the Up and Down Arrow keys, when JAWS read the headers and associated text if expanded in a linear order.
- 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.
- NVDA version 2018.4.1
- Chrome version 72.0.3626.96 (Official Build) (64-bit)
- Carbon React version 7.7.1
- The Tab key and Shift-Tab navigate between accordion headers. NVDA announces, title, and expand/collapse status.
- Press the Enter or Space key on the title. NVDA announces expand or collapsed.
- 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
- Safari version 13.1.3
- Carbon React version 7.7.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.
- To expand or collapse the accordion, doubletap on the header, or press Control+Option+Space. VoiceOver announces, exapnaded or collapses.
- 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.
- 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
- Chrome version 72.0.3626.96 (Official Build) (64-bit)
- Carbon React version 7.7.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.
- To expand or collapse the accordion, doubletap on the header, or press Alt+Enter. Talkback announces expanded or collapses.
- 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.