Skip to content
PatternFly logo

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:

  • This ensures that users can more quickly scan through the accordion contents without having to expand individual panels.
  • Tab navigates to the next accordion toggle or focusable element, and Shift + Tab navigates to the previous accordion toggle or focusable element.
  • 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 describing the accordion component]"
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.
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 describing 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 describing the accordion component]"
.pf-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-c-accordion__toggle
Indicates whether the accordion toggle is expanded (true) or collapsed (false) to assistive technologies. Required.
aria-label="[text describing the accordion content]"
.pf-c-accordion__expanded-content
Adds an accessible name to the content of an accordion item.
hidden
.pf-c-accordion__expanded-content
Hides the accordion content. Required when aria-expanded="false" is passed in.
aria-hidden="true"
.pf-c-accordion__toggle-icon
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.

Further reading

To read more about accessibility with accordions, refer to the following resources:


View source on GitHub