Accordion

An accordion is an interactive container that expands and collapses to hide or reveal nested content. It takes advantage of progressive disclosure to help reduce page scrolling, by allowing users to choose whether they want to show or hide more detailed information as needed.

Accessibility

To implement an accessible PatternFly accordion:

Give each accordion toggle a unique and descriptive label.

For the PatternFly React library:

Include the isExpanded prop on the accordion toggle based on the toggle's state.

For the HTML/CSS library:

Include the aria-expanded attribute on the accordion toggle based on the toggle's state.

Testing

At a minimum, an accordion should meet the following criteria:

Each accordion toggle includes unique and descriptive labels.This ensures that users can more quickly scan through the accordion contents without having to expand individual panels.
Standard keyboard navigation can be used to navigate between accordion toggles or other focusable elements.Tab navigates to the next accordion toggle or focusable element, and Shift + Tab navigates to the previous accordion toggle or focusable element.
Accordion toggles can be collapsed or expanded via keyboard by pressing Space or Enter.
If headings are used in an accordion toggle, heading levels are not skipped within the context surrounding the accordion.
A user navigating via a screen reader will be notified of the current accordion toggle state, as well as when that state gets updated.This can be checked with a screen reader, or by checking that the aria-expanded attribute is accurate and updating in the DOM.

React customization

The following React props have been provided for more fine-tuned control over accessibility.

Prop	Applied to	Reason
`aria-label="[text that labels the accordion component]"`	`Accordion`	Adds an accessible name to the accordion for assistive technologies. If there is no other surrounding context provided for an accordion, especially if there are multiple accordions on a page, this should be passed in with descriptive text.
`headingLevel="[a heading tag]"`	`Accordion`	When `asDefinitionList={false}` is passed in, sets the container for the accordion toggle to one of the six heading elements (`h3` by default). Be sure to not skip heading levels when passing this prop in. For example, if an accordion is within a page section that has an `h2` heading, you should not pass `headingLevel="h4"`.
`aria-label="[text that labels the accordion content]"`	`AccordionContent`	Adds an accessible name to the content of an accordion item.
`isHidden`	`AccordionContent`	Determines whether the content of the accordion item is hidden or not. Should be used along with the `isExpanded` prop on the accordion toggle.
`isExpanded`	`AccordionToggle`	Adds styling to visually determine whether the toggle is expanded or collapsed. Also sets the accessibility attribute `aria-expanded` with a value of "true" or "false", which notifies screen readers whether the accordion toggle is expanded ("true") or collapsed ("false"). Should be used along with the `isHidden` prop on the accordion content.

isHidden and isExpanded

The isHidden and isExpanded props should always have opposite values of one another; if an accordion toggle is collapsed (isExpanded={false}), then the accordion content should be hidden (isHidden={true}). For example:

const [expandedItem, setExpandedItem] = React.useState('accordion-item-1');

<Accordion>
  <AccordionItem>
    <AccordionToggle
      isExpanded={expanded === 'accordion-item-1'}
    >
      Toggle text...
    </AccordionToggle>
    <AccordionContent isHidden={expanded !== 'accordion-item-1'}>
      Content text...
    </AccordionContent>
  </AccordionItem>
</Accordion>

Aria-label

Passing in the aria-label prop to the accordion component can be helpful when there are multiple accordions on a page, or when there is no other surrounding context:

<Accordion aria-label="Billing questions">
  ...
</Accordion>

<Accordion aria-label="Return and refund questions">
  ...
</Accordion>

HTML/CSS customization

The following HTML attributes and PatternFly classes can be used for more fine-tuned control over accessibility.

Attribute or class	Applied to	Reason
`aria-label="[text that labels the accordion component]"`	`.pf-v5-c-accordion`	Adds an accessible name to the accordion for screen readers. If there is no other surrounding context provided for an accordion, especially if there are multiple accordions on a page, this should be passed in with descriptive text. See the aria-label prop example in the React customization section.
`aria-expanded="[true or false]"`	`.pf-v5-c-accordion__toggle`	Indicates whether the accordion toggle is expanded (true) or collapsed (false) to assistive technologies. Required.
`aria-label="[text that labels the accordion content]"`	`.pf-v5-c-accordion__expanded-content`	Adds an accessible name to the content of an accordion item.
`hidden`	`.pf-v5-c-accordion__expanded-content`	Hides the accordion content. Required when `aria-expanded="false"` is passed in.
`aria-hidden="true"`	`.pf-v5-c-accordion__toggle-icon > i`	Removes the accordion toggle icon from the accessibility tree, preventing assistive technologies from potentially announcing duplicate or unnecessary information without visually hiding it. Required.

Additional considerations

Consumers must ensure they take any additional considerations when customizing an accordion, using it in a way not described or recommended by PatternFly, or in various other specific use-cases not outlined elsewhere on this page.

Avoid adding complex interaction to the accordion. This can often cause loops or traps that prevent users from efficiently navigating the content when using a keyboard.