React Accessible Accordion — install, keyboard navigation, ARIA & customization

Quick answer: react-accessible-accordion is a lightweight, ARIA-compliant React component for building collapsible panels and FAQ accordions. It handles roles, keyboard navigation, and focus management so you can ship accessible collapsible content fast.

This guide shows how to install it, implement keyboard-friendly accordions, customize behavior and styling, and include small snippets ready to copy into your React app. It also includes a semantic core and recommended microdata for SEO and voice search.

Why choose react-accessible-accordion for collapsible React content?

The central benefit is clear: it implements WAI-ARIA best practices out of the box. That means screen readers get correct role, state and relationship annotations. The library manages focus, expanded/collapsed states, and keyboard interactions (Arrow keys, Home/End, Enter/Space) so your UI behaves consistently across assistive tech.

Beyond accessibility, the component is intentionally small and composable. You bring your own markup and styles while the library supplies the semantics and interaction layer. That makes it a fit whether you’re building a simple FAQ or a complex settings panel with nested accordions.

Finally, because accessibility is baked in, you reduce long-term maintenance: fewer ad-hoc ARIA attributes, fewer edge-case keyboard bugs, and easier audits. And yes — it also helps SEO indirectly by making content discoverable to assistive crawlers and enabling clear content structure for featured snippets.

Getting started: installation and basic setup

To begin, install the library from npm or yarn. The following commands work in most React projects (Create React App, Vite, Next.js, etc.).

npm install react-accessible-accordion
# or
yarn add react-accessible-accordion

Import the components you need. The simplest pattern uses Accordion, AccordionItem, AccordionItemHeading, AccordionItemButton, and AccordionItemPanel. The library exports these building blocks so you can style markup while keeping proper ARIA roles intact.

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

Here is a minimal working example. Drop this into a component to see a basic accessible accordion in action.

function FAQ() {
  return (
    <Accordion allowZeroExpanded>
      <AccordionItem>
        <AccordionItemHeading>
          <AccordionItemButton>What is react-accessible-accordion?</AccordionItemButton>
        </AccordionItemHeading>
        <AccordionItemPanel>
          <p>A small library that provides ARIA-compliant accordion components for React.</p>
        </AccordionItemPanel>
      </AccordionItem>
    </Accordion>
  );
}

This example demonstrates the most important props and structure: Accordion wraps items, each item has a heading and control (button) plus a panel. The library wires ARIA and keyboard semantics automatically.

Keyboard navigation, ARIA roles, and focus management

Keyboard navigation is essential for accessibility and is one of the key reasons to use this library. The component implements the ARIA Authoring Practices for accordions: Tab to focus a header button, Enter/Space toggles the panel, Arrow Up/Down (or Left/Right depending on configuration) moves focus between headers, and Home/End jump to first/last headers.

Under the hood, the library adds role=”button” and aria-expanded attributes to the header button and uses aria-controls to link the button to the collapsible panel. These attributes are critical for screen readers because they convey state and the relationship between controls and content.

If you need to adjust keyboard behavior you can intercept events or use the library’s props (e.g., allowMultipleExpanded, allowZeroExpanded) to change how focus and expansion work. For advanced cases, you can manage expanded state externally to integrate with global shortcuts or other accessibility patterns.

Customization: styling, icons, controlled mode, and multiple open items

Styling the accordion is purely CSS-driven — you control the button and panel classes. The library does not force styles, which means you can match your design system or framework. Use the className prop on AccordionItem, or wrap children and style the inner elements directly.

Want icons that rotate or animate? Wrap the AccordionItemButton content and add a CSS transition on a modifier class that you toggle when aria-expanded="true" is present. Because the DOM includes standard attributes, you can target them in CSS selectors without hacking into library internals.

For programmatic control, manage expanded state outside the library: use controlled mode by tracking expanded item IDs and passing them into Accordion. This is useful when you need deep-linking (open a specific panel based on URL hash), synchronized panels across components, or persisting the open state in localStorage.

• Key props: allowMultipleExpanded, allowZeroExpanded, preExpanded (IDs), onChange callback.
• Styling: className or wrap inner elements; target [aria-expanded=”true”] for state selectors.

Examples and patterns — FAQ accordion, nested content, and dynamic panels

Common usage patterns include FAQ lists, progressive disclosure in forms, and mobile accordion menus. For FAQ pages, structure each question as a heading/button and the answer as the panel content. Keep answers concise and include semantic HTML (paragraphs, lists, code blocks) inside the panel for readability.

Nested accordions are supported but require care: ensure focus management is scoped correctly so arrow key navigation doesn’t inadvertently jump between nested sets. Often the easiest approach is to disable arrow-key rotation on inner accordions and let Tab navigate into nested content.

For dynamic content (e.g., panels derived from an API), render AccordionItems with stable keys/IDs and pass an array of preExpanded IDs if you need initial open panels. When mapping items, use unique identifiers rather than array indices to avoid state mismatches when items change order.

// Sample dynamic FAQ mapping
const faqs = [{id:'q1', q:'How to install?', a:'Run npm i react-accessible-accordion'}, ...];

<Accordion preExpanded={['q1']}>
  {faqs.map(item => (
    <AccordionItem key={item.id} uuid={item.id}>
      ...
    </AccordionItem>
  ))}
</Accordion>

Performance, SSR and best practices

The library is client-side JavaScript. For server-side rendering (Next.js, Remix), render the structural markup on the server and hydrate on the client — that’s the standard approach. Avoid client-only conditional rendering of Accordion children if SEO or crawlability matters; render content server-side where possible and hide via attributes or CSS so bots can index it.

Lazy-loading heavy panel content can improve initial load performance. Consider loading media, charts, or external widgets only when the panel opens. Use the library’s onChange handler to trigger a lazy fetch or mount when a panel becomes expanded.

Accessibility testing: use keyboard navigation, screen-reader testing (NVDA, VoiceOver), and automated tools (axe, Lighthouse) to validate behavior. Also verify that focus order and visible focus ring styles meet your design standards — an accessible component is only useful if it’s visible and obvious to keyboard users.

SEO and voice-search optimization (featured snippet & voice-friendly answers)

To optimize for featured snippets and voice search, put short direct answers at the top of pages or immediately under each question heading in FAQ panels. Voice assistants prefer concise answers (one- to two-sentence definitions) followed by longer explanatory content that adds context.

Use clear semantic headings (H2/H3) for each question and include schema.org FAQPage microdata so search engines can surface your Q&As directly in search. Below is a recommended JSON-LD snippet for the FAQ section — include it in your page head or before the closing body tag.

{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "How do I install react-accessible-accordion?",
      "acceptedAnswer": { "@type": "Answer", "text": "Run npm install react-accessible-accordion or yarn add react-accessible-accordion and import the components into your React file." }
    },
    {
      "@type": "Question",
      "name": "Does react-accessible-accordion support keyboard navigation?",
      "acceptedAnswer": { "@type": "Answer", "text": "Yes. It implements ARIA Authoring Practices: Tab, Enter/Space, Arrow keys, Home/End, and handles focus management." }
    },
    {
      "@type": "Question",
      "name": "How do I customize styles and allow multiple panels open?",
      "acceptedAnswer": { "@type": "Answer", "text": "Use props allowMultipleExpanded and className. Style based on [aria-expanded] attributes or your custom classes." }
    }
  ]
}

FAQ — top user questions

Semantic core (primary, secondary, clarifying keywords)