Accordion

The sidebar accordion, used in listing pages or as navigation, can hold multiple navigation items or to be used as a filter for content.

Each tab styling can be changed to open or collapse using aria-expanded, set true for open and false to close. Using JS this can be changed and to point to what each tab controls via aria-controls.

.p-accordion__panel visibility is affected by aria-hidden and again can be manipulated with JS.

Each tab button element should be wrapped by an element with a .p-accordion__heading class, per the W3C accessibility guidelines on accordions.

The wrapping element should either be a heading element or a div element with the attributes role="header" and aria-level set. aria-level should be set to the value appropriate within the page hierarchy.

With aria attributes:

With heading elements:

With tick elements

When checkboxes or radio buttons are used inside accordion panels add has-tick-elements class name to the panel p-accordion__panel element, to properly align tick elements with accordion controls.

Functionality

Please ensure the aria-control attribute matches an ID of an element. If aria-expanded is true, then the accordion will be open by default. When clicking on the accordion__tab, you must toggle the aria-expanded attribute on the toggle and the aria-hidden attribute on the panel.

Accessibility

How it works

Accordions are a vertically stacked list of headings. They reduce the need for users to scroll through a lot of content, as the headings act as interactive elements which show or hide the related content.

Tab and Shift-Tab are used to navigate forward and backward through each accordion header and all focusable elements in the accordion should be included in the tab order. Enter or Space expand and collapse each accordion panel.

The two main components are:

• Accordion heading which is the interactive title or thumbnail for each section. The headings can hide or show content.
• Accordion panel is the content associated with an accordion heading.

Considerations

This component strives to follow WCAG 2.1 (level AA) guidelines, and care must be taken to ensure this effort is maintained when the component is implemented across other projects. This section offers advice to that effect:

• Accordion titles should be descriptive; it should be obvious what information the content will contain.
• Ensure each tab button element is wrapped by a div element with a p-accordion__heading class and the role=heading attribute. This heading should have an appropriate aria-level label, depending on its position in the hierarchy of the page.
• If the accordion panel associated with the heading is visible, then the button within the heading div must have aria-expanded=”true”
• The heading button should have an aria-controls attribute set to the ID of the related accordion panel.
• Add the aria-labelledby attribute to the accordion panel, set to the ID of the button heading.
• 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.

Resources

• W3C WAI-ARIA Accordion (Sections With Show/Hide Functionality)
• WAI-ARIA Examples: Accordion
• Carbon design systems - Accordion accessibility
• Guidelines:
  • 1.3.1: Info and Relationships
  • 2.1.1: Keyboard Accessible
  • 2.1.2: No Keyboard Trap

Import

To import just this component into your project, copy the snippet below and include it in your main Sass file.

// import Vanilla and include base mixins
// this only needs to happen once in a given project
@import 'vanilla-framework';
@include vf-base;

@include vf-p-accordion;

For more information see Customising Vanilla in your projects, which includes overrides and importing instructions.

React

You can use accordion in React by installing our react-component library and importing Accordion component.

See the documentation for our React Accordion component