React Accessible Accordion

Common errors

• Accessibility features like `role="region"` are missing on accordion panels

  cause The `role="region"` attribute on `AccordionItemPanel` was removed by default in v4.0.0.
  fix Add the `region` boolean prop to your `AccordionItemPanel` component (e.g., `<AccordionItemPanel region>`) to re-enable the role.

• console.error: Provided with invalid HTML5 ids

  cause The accordion components, particularly `AccordionItemHeading` or `AccordionItemButton`, were likely passed `id` props that are not valid HTML5 IDs, or duplicate IDs were generated/provided.
  fix Ensure that any `id` props provided manually are unique and adhere to HTML5 ID naming conventions. If not providing IDs, ensure the library's automatic ID generation functions correctly without conflicts, especially in complex or dynamic rendering scenarios.

• Module not found: Can't resolve 'react-accessible-accordion/dist/fancy-example.css' in ...

  cause The path to the demo stylesheet is incorrect, or the file is not available in the expected location (e.g., due to build issues or incorrect `node_modules` structure).
  fix Verify the import statement `import 'react-accessible-accordion/dist/fancy-example.css';` is correct. If issues persist, manually locate the file in `node_modules` or download its contents and include it directly in your project.

Warnings

• gotcha The project is officially 'no longer maintained' by its creators. They strongly recommend using native HTML `<details>` and `<summary>` elements for new implementations due to their inherent performance, accessibility, and framework-agnostic benefits.
  Fix: For new implementations, consider using native `<details>` and `<summary>` HTML elements. For existing projects, be aware that active development and new features are unlikely.
• breaking Starting with v4.0.0, the `AccordionItemPanel` component no longer includes `role="region"` by default. This change was based on WAI-ARIA guidelines, as `region` is often redundant and can clutter the accessibility tree.
  Fix: If `role="region"` is still desired for specific use cases, add the `region` boolean prop directly to the `AccordionItemPanel` component (e.g., `<AccordionItemPanel region>`).
• breaking Version 5.0.0 introduced React 18 support, leveraging the `useId` hook for improved out-of-order streaming. While this primarily adds compatibility, it might imply certain expectations or behaviors when integrating with older React versions or complex server-side rendering setups if not handled carefully.
  Fix: Ensure your React environment is compatible with the `useId` hook if you are targeting specific React 18 features. For older React versions, peer dependencies `^16.3.2 || ^17.0.0 || ^18.0.0` still allow usage, but be mindful of potential SSR hydration issues specific to `useId` if encountering them.
• gotcha The library provides minimal to no default styling. The `fancy-example.css` stylesheet is intended for demonstration purposes only and should not be used in production directly without modification. Developers are expected to provide their own styles.
  Fix: Copy the contents of `fancy-example.css` into your project and adapt them, or create entirely new styles for your accordion components. Importing `react-accessible-accordion/dist/fancy-example.css` is only a quick way to get some basic visual feedback.

Install

• npm install react-accessible-accordion npm
• yarn add react-accessible-accordion yarn
• pnpm add react-accessible-accordion pnpm

Imports

• Accordion
  wrong:

  const Accordion = require('react-accessible-accordion').Accordion;

  correct:

  import { Accordion } from 'react-accessible-accordion';

  Primary container component for the accordion.
• AccordionItem
  wrong:

  import AccordionItem from 'react-accessible-accordion/AccordionItem';

  correct:

  import { AccordionItem } from 'react-accessible-accordion';

  Represents an individual expandable/collapsible item within the Accordion. All core components are named exports.
• styles
  wrong:

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

  correct:

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

  The library does not include default styles; this path imports a demo stylesheet that can be used as a starting point. It's recommended to copy and customize these styles or write your own.

Quickstart

Demonstrates a basic accessible accordion with two expandable items, using named imports for components and an optional demo stylesheet. It also explicitly shows `uuid` for consistent IDs, although often automatically generated.

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

// Optional: Import demo styles, or create your own.
import 'react-accessible-accordion/dist/fancy-example.css';

export default function BasicAccordionExample() {
    // Configure accordion behavior with props like allowMultipleExpanded and allowZeroExpanded
    return (
        <Accordion allowZeroExpanded>
            <AccordionItem uuid="item-1">
                <AccordionItemHeading>
                    <AccordionItemButton>
                        What is React?
                    </AccordionItemButton>
                </AccordionItemHeading>
                <AccordionItemPanel>
                    <p>
                        React is a free and open-source front-end JavaScript library for building user interfaces based on UI components.
                    </p>
                </AccordionItemPanel>
            </AccordionItem>
            <AccordionItem uuid="item-2">
                <AccordionItemHeading>
                    <AccordionItemButton>
                        Why use an accessible accordion?
                    </AccordionItemButton>
                </AccordionItemHeading>
                <AccordionItemPanel>
                    <p>
                        Accessible accordions ensure that all users, including those using assistive technologies, can easily navigate and interact with collapsed and expanded content.
                    </p>
                </AccordionItemPanel>
            </AccordionItem>
        </Accordion>
    );
}