react-accessible-accordion

react-accessible-accordion

Demo

Try a demo now.

Usage

First, grab the package from npm:

npm install --save react-accessible-accordion

Then, import the editor and use it in your code. Here is a basic example:

import React from 'react';

import {
    Accordion,
    AccordionItem,
    AccordionItemHeading,
    AccordionItemPanel,
} from 'react-accessible-accordion';

// Demo styles, see 'Styles' section below for some notes on use.
import 'react-accessible-accordion/dist/fancy-example.css';

export default function Example() {
    return (
        <Accordion>
            <AccordionItem>
                <AccordionItemHeading>
                    <AccordionItemButton>
                        What harsh truths do you prefer to ignore?
                    </AccordionItemButton>
                </AccordionItemHeading>
                <AccordionItemPanel>
                    <p>
                        Exercitation in fugiat est ut ad ea cupidatat ut in
                        cupidatat occaecat ut occaecat consequat est minim minim
                        esse tempor laborum consequat esse adipisicing eu
                        reprehenderit enim.
                    </p>
                </AccordionItemPanel>
            </AccordionItem>
            <AccordionItem>
                <AccordionItemHeading>
                    <AccordionItemButton>
                        Is free will real or just an illusion?
                    </AccordionItemButton>
                </AccordionItemHeading>
                <AccordionItemPanel>
                    <p>
                        In ad velit in ex nostrud dolore cupidatat consectetur
                        ea in ut nostrud velit in irure cillum tempor laboris
                        sed adipisicing eu esse duis nulla non.
                    </p>
                </AccordionItemPanel>
            </AccordionItem>
        </Accordion>
    );
}

Styles

We strongly encourage you to write your own styles for your accordions, but we've published the styles used on our demo page to help you get up and running:

import 'react-accessible-accordion/dist/fancy-example.css';

We recommend that you copy them into your own app and modify them to suit your needs, particularly if you're using your own classNames.

Component API

Accordion

allowMultipleExpanded : boolean [optional, default: false]

Don't autocollapse items when expanding other items.

allowZeroExpanded : boolean [optional, default: false]

Allow the only remaining expanded item to be collapsed.

preExpanded: string[] [optional, default: []]

Accepts an array of strings and any AccordionItem whose uuid prop matches on of these strings will be expanded on mount.

className : string [optional, default: 'accordion']

Class(es) to apply to element.

onChange : (string[]) => void [optional]

Callback which is invoked when items are expanded or collapsed. Gets passed uuids of the currently expanded AccordionItems.

---

AccordionItem

className : string [optional, default: accordion__item]

Class(es) to apply to element.

uuid : string|number [optional]

Recommended for use with onChange. Will be auto-generated if not provided.

---

AccordionItemHeading

className : string [optional, default: 'accordion__heading']

Class(es) to apply to the 'heading' element.

aria-level : number [optional, default: 3]

Semantics to apply to the 'heading' element. A value of 1 would make your heading element hierarchically equivalent to an <h1> tag, and likewise a value of 6 would make it equivalent to an <h6> tag.

AccordionItemButton

className : string [optional, default: 'accordion__button']

Class(es) to apply to the 'button' element.

---

AccordionItemPanel

className : string [optional, default: 'accordion__panel']

Class(es) to apply to element.

---

AccordionItemState

children : ({ expanded: boolean, disabled: boolean }): JSX.Element [required]

---

Helpers

resetNextUuid : (): void

Resets the internal counter for Accordion items' identifiers (including id attributes). For use in test suites and isomorphic frameworks.

---

Accessibility Best-Practice

Authoring an 'accordion' component to the WAI ARIA spec can be complex, but React Accessible Accordion does most of the heavy lifting for you, including:

• Applying appropriate aria attributes (aria-expanded, aria-controls, aria-disabled, aria-hidden and aria-labelledby).
• Applying appropriate role attributes (button, heading, region).
• Applying appropriate tabindex attributes.
• Applying keyboard interactivity ('space', 'end', 'tab', 'up', 'down', 'home' and 'end' keys).

However, there's still a couple of things you need to keep in mind to remain spec-compliant:

• Only ever use phrasing content inside of your AccordionItemHeading component. If in doubt, use text only.
• Always provide an aria-level prop to your AccordionItemHeading component, especially if you are nesting accordions. This attribute is a signal used by assistive technologies (eg. screenreaders) to determine which heading level (ie. h1-h6) to treat your heading as.

If you have any questions about your implementation, then please don't be afraid to get in touch via our issues.

FAQs

Which design patterns does this component aim to solve?

Those described by the WAI ARIA spec's description of an 'accordion':

An accordion is a vertically stacked set of interactive headings that each contain a title, content snippet, or thumbnail representing a section of content. The headings function as controls that enable users to reveal or hide their associated sections of content. Accordions are commonly used to reduce the need to scroll when presenting multiple sections of content on a single page.

Which design patterns does this component NOT aim to solve?

Components which are "accordion-like" but do not match the WAI ARIA spec's description, as written above. By "accordion-like", we mean components which have collapsible items but require bespoke interactive mechanisms in order to expand, collapse and 'disable' them. This includes (but is not limited to) multi-step forms, like those seen in many cart/checkout flows, which we believe require (other) complex markup in order to be considered 'accessible'.

If you believe that you have a valid use-case for 'disabled' items, or items which require manual 'expanded' state-management, then please let us know - we're always open for critical (but polite) feedback. Otherwise, we don't plan on implementing this functionality in the near future.

How do I disable an item?

See "Which design patterns does this component NOT aim to solve?".

How do I manually control the expanded state of an item?

See "Which design patterns does this component NOT aim to solve?". You may use the 'preExpanded' prop to set the initial expanded state, but it may not be controlled manually thereafter.

Browser Support

Supported browser / device versions:

Browser	Device/OS	Version
Mobile Safari	iOS	latest
Chrome	Android	latest
IE	Windows	11
MS Edge	Windows	latest
Chrome	Desktop	latest
Firefox	Desktop	latest
Safari	OSX	latest

Changelog

[v3.0.0]

This release is the culmination of a massive amount of work, resulting in some new features and significantly stronger and more reliable WAI ARIA spec compliance. Notably, the project has been migrated from Flow to Typescript, and a full accessibility audit has been performed - revealing a few holes in our compliance which have now been entirely addressed.

Thanks to everyone who has contributed to this release - and not just those who have written code. Contribution by way of issues relating to spec compliance, pull-request commentary, advice and assistance is all greatly appreciated. Thanks also to the patient users who have endured an extended period without a release while we made sure to get this 100% right! Release cadence should return to normal again now.

Breaking Changes - Upgrade Guide:

1. Rename all of your AccordionItemTitle components to AccordionItemHeading and then nest an AccordionItemButton directly inside of each one. Note that in order for your Accordion to remain spec-compliant, you may not put any other children inside AccordionItemHeading.

   // Before:
   import { AccordionItemTitle } from 'react-accessible-accordion';
   
   const headingBefore = <AccordionItemTitle>Foo</AccordionItemTitle>;
   

   //  After:
   import {
       AcccordionItemHeading,
       AccordionItemButton,
   } from 'react-accessible-accordion';
   
   const headingAfter = (
       <AccordionItemHeading>
           <AccordionItemButton>Foo</AccordionItemButton>
       </AccordionItemHeading>
   );
   

2. Rename all of your AccordionItemBody components to AccordionItemPanel.

   // Before:
   import { AccordionItemBody } from 'react-accessible-accordion';
   
   const panelBefore = (
       <AccordionItemBody>
           Voluptate elit eiusmod laborum proident esse officia dolor laboris
           laboris amet nulla officia cillum.
       </AccordionItemBody>
   );
   

   // After:
   import { AccordionItemPanel } from 'react-accessible-accordion';
   
   const panelAfter = (
       <AccordionItemPanel>
           Voluptate elit eiusmod laborum proident esse officia dolor laboris
           laboris amet nulla officia cillum.
       </AccordionItemPanel>
   );
   

3. Remove all instances of hideBodyClassName. This prop is no longer valid, as AccordionItemPanel components are now hidden without additional styling. If you must have a different className prop when an item is collapsed, then you may leverage the new AccordionItemState component.

   // Before
   import { AccordionItemPanel } from 'react-accessible-accordion';
   
   const panelBefore = (
       <AccordionItemPanel className="foo" hideBodyClassName="foo--hidden" />
   );
   

   // After:
   import {
       AccordionItemPanel,
       AccordionItemState,
   } from 'react-accessible-accordion';
   
   const panelAfter = (
       <AccordionItemState>
           {({ expanded }) => (
               <AccordionItemPanel
                   className={expanded ? 'foo' : 'foo foo--hidden'}
               />
           )}
       </AccordionItemState>
   );
   

4. Remove all instances of AccordionItem’s expanded prop and instead use Accordion’s preExpanded prop. Note that this means that ‘controlled’ accordions are no longer a supported pattern. Please raise an issue if you have a use-case which calls for the ability to manually control expanded state.

   // Before
   import { Accordion, AccordionItem } from 'react-accessible-accordion';
   
   const accordionBefore = (
       <Accordion>
           <AccordionItem expanded />
       </Accordion>
   );
   

   // After:
   import { Accordion, AccordionItem } from 'react-accessible-accordion';
   
   const accordionAfter = (
       <Accordion preExpanded={['foo']}>
           <AccordionItem uuid="foo" />
       </Accordion>
   );
   

5. Remove all instances of Accordion’s accordion prop. Instead, use a combination of allowZeroExpanded and allowMultipleExpanded props to suit your requirements. If you were not explicitly setting accordion to false then you probably are not required to make any changes here.

   // Before
   import { Accordion } from 'react-accessible-accordion';
   
   const accordionBefore = <Accordion accordion={false} />;
   

   // After:
   import { Accordion } from 'react-accessible-accordion';
   
   const accordionAfter = <Accordion allowMultipleExpanded />;
   

6. Upgrade to React v16.3+

7. Remove your minimal-example.css import. These styles only applied display: none to panels when collapsed, but browsers apply these styles to elements with the hidden attribute, which the AccordionItemPanel component now has (when collapsed).

Added

• Added AccordionItemButton component.
• Added AccordionItemState component.
• Added allowZeroExpanded prop to Accordion.
• Added allowMultipleExpanded prop to Accordion.
• Out-of-the-box Typescript support.
• Integration tests to explicitly assert every line of the WAI ARIA 'Accordion' spec.
• Additional keyboard functionality (Up, Down, Left, Right, Home, End).

Changed

• Renamed AccordionItemTitle to AccordionItemHeading to be consistent with the language used in the WAI ARIA spec.
• Renamed AccordionItemBody to AccordionItemPanel to be consistent with the language used in the WAI ARIA spec.
• Updated AccordionItemPanel to have a hidden attribute.
• Roles and aria attributes all audited and updated to match the WAI ARIA spec.
• Update onChange to always be called with an array of the currently expanded items.

Fixed

• Fixes SSR (server-side rendering).
• Fixes incorrect roles and attributes as per the WAI ARIA spec.

Removed

• Removed Flow support (but we hope to reinstate typing in the future. Track progress here).
• Removed undocumented expanded mechanism for AccordionItems.
• Removed undocumented disabled mechanism for AccordionItems.
• Remove hideBodyClassName prop.