🅰 An accessible and versatile accordion for React with keyboard navigation and labeling features taught in w3.org's WAI-ARIA accordion best practices example
- npm i @accessible/accordion
An accessible and versatile accordion for React with keyboard navigation and labeling features taught in
w3.org’s WAI-ARIA accordion best practices example.
style objects, anything!Check out the example on CodeSandbox
```jsx harmony
import {Accordion, Section, Trigger, Panel} from ‘@accessible/accordion’
const Component = () => (
<Section><h3><Trigger><button>Section 2</button></Trigger></h3><Panel><div className="panel">Section 2 content</div></Panel></Section>
)
## API### Components| Component | Description || --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- || [`<Accordion>`](#accordion) | This component creates the context for your accordion section and contains some configuration options. || [`<Section>`](#section) | This component creates the context for the accordion panel and trigger contained in this section. It must be a direct descendent of [`<Accordion>`](#accordion). || [`<Trigger>`](#trigger) | This component clones any React element and turns it into a accordion trigger that controls the visible state of the panel. || [`<Panel>`](#panel) | This component clones any React element and turns it into a accordion panel. || [`<Close>`](#close) | This is a convenience component that clones any React element and adds an onClick handler to close its parent panel. | |### Hooks| Hook | Description || --------------------------------- | --------------------------------------------------------------------------------------------------------------------- || [`useAccordion()`](#useaccordion) | This hook returns the value of the accordion's [AccordionContext object](#accordioncontextvalue). || [`useSection()`](#usesection) | This hook returns the value of the accordion [`<Section>`'s](#section) [SectionContext object](#sectioncontextvalue). || [`useControls()`](#usecontrols) | This hook returns the accordion [`<Section>`'s](#section) `open`, `close`, and `toggle` functions. || [`useDisabled()`](#usedisabled) | This hook returns the accordion [`<Section>`'s](#section) `disabled` value. || [`useIsOpen()`](#useisopen) | This hook returns the accordion [`<Section>`'s](#section) `isOpen` value. |### `<Accordion>`This component creates the context for your accordion section and contains some configuration options.[`<Section>`s](#section) are the only type of children allowed.#### Props| Prop | Type | Default | Required? | Description || ----------------- | ----------------------------------------------------- | ----------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- || defaultOpen | <code>number | number[]</code> | `undefined` | No | The section by index (or sections if `allowMultipleOpen`) you want opened by default. || open | <code>number | number[]</code> | `undefined` | No | Makes this a controlled component where `open`, `close`, `toggle`, controls have no effect. The sections defined here are always the ones that are open. || allowMultipleOpen | `boolean` | `false` | No | Allows multiple sections to be opened at one time. || allowAllClosed | `boolean` | `false` | No | Allows all of the sections to be closed. If `false`, you must define either the `open` or `defaultOpen` property. || onChange | <code>(opened: number | number[]) => void</code> | `undefined` | No | Called each time the open sections change. If `allowMultipleOpen`, the argument will be an array, otherwise a single number. The number corresponds to the open section's index. || children | `React.ReactElement<SectionProps>[]` | `undefined` | Yes | The only children allowed by this component are [`<Section>`s](#section). |### `<Section>`This component creates the context for the accordion panel and trigger contained in this section. It must be a directdescendent of [`<Accordion>`](#accordion).#### Props| Prop | Type | Default | Required? | Description || -------- | --------------------------------------------------------------------------------------- | ----------- | --------- | ---------------------------------------------------------------------------------------------------------------- || id | `string` | `undefined` | No | Overrides the ID that is auto-generated by this component. || disabled | `boolean` | `false` | No | `true` if the section should not be allowed to have its `open` state changed. || children | <code>React.ReactNode | ((context: SectionContextValue) => React.ReactNode)</code> | `undefined` | Yes | Sections must include a [`<Trigger>`](#trigger) and a [`Panel`](#panel) in addition to anything else you'd like. |### `<Trigger>`This component clones any React element and turns it into a accordion trigger that controls the visible state ofthe [`<Panel>`](#panel). It must be a child of [`<Section>`](#section).#### Props| Prop | Type | Default | Required? | Description || ----------- | --------------------- | ----------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- || openClass | `string` | `undefined` | No | This class name will be applied to the child element when the section is `open`. || closedClass | `string` | `undefined` | No | This class name will be applied to the child element when the section is `closed`. || openStyle | `React.CSSProperties` | `undefined` | No | These styles will be applied to the child element when the section is `open`. || closedStyle | `React.CSSProperties` | `undefined` | No | These styles will be applied to the child element when the section is `closed`. || children | `React.ReactElement` | `undefined` | Yes | The child is cloned by this component and has aria attributes injected into its props as well as keyboard events for opening the section with `space` and `enter` keys and navigating between sections. |### `<Panel>`This component clones any React element and turns it into a accordion section panel. It must bea child of [`<Section>`](#section).#### Props| Prop | Type | Default | Required? | Description || ----------- | --------------------- | ----------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- || openClass | `string` | `undefined` | No | This class name will be applied to the child element when the section is `open`. || closedClass | `string` | `undefined` | No | This class name will be applied to the child element when the section is `closed`. || openStyle | `React.CSSProperties` | `undefined` | No | These styles will be applied to the child element when the section is `open`. || closedStyle | `React.CSSProperties` | `undefined` | No | These styles will be applied to the child element when the section is `closed`. || children | `React.ReactElement` | `undefined` | Yes | The child is cloned by this component and has aria attributes injected into its props as well as keyboard events for closing the section with the `escape` key. |### `<Close>`This is a convenience component that clones any React element and adds an onClick handler to close its parent panel. Itmust be a child of [`<Section>`](#section).#### Props| Prop | Type | Default | Required? | Description || -------- | -------------------- | ----------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ || children | `React.ReactElement` | `undefined` | Yes | The child is cloned by this component and has aria attributes injected into its props as keyboard events to ensure it acts like a button even if it isn't a native `<button>`. |### `useAccordion()`This hook returns the value of the accordion's [AccordionContext object](#accordioncontextvalue). This hookmust be within a child of [`<Accordion>`](#accordion).### `AccordionContextValue````typescript jsxinterface AccordionContextValue {// DOM references to the accordion sectionssections: (HTMLElement | undefined)[]// Registers a new accordion sectionregisterSection: (index: number, trigger: HTMLElement) => () => void// The indexes of the open sectionsopened: number[]// Opens a sectionopen: (section: number | undefined) => void// Closes a sectionclose: (section: number | undefined) => void// Returns true if a section is openisOpen: (section: number | undefined) => boolean// Does the accordion allow all of its sections to be closed?allowAllClosed: boolean}
useSection()This hook returns the value of the accordion sections’s SectionContextValue object. This hook
must be within a child of <Section>.
SectionContextValuetypescript jsx
interface SectionContextValue {
// Is this section open?
isOpen: boolean
// Opens this section if not disabled
open: () => void
// Closes this section if possible
close: () => void
// Toggles the visible state of this section if possible
toggle: () => void
// The id of this section
id?: string
// The index of this section
index: number
// Is the section disabled?
disabled: boolean
// The DOM reference to the section's <Trigger>
triggerRef: React.MutableRefObject<HTMLElement | null>
}
useControls()This hook returns the accordion sections’s open, close, and toggle functions. This hook
must be within a child of <Section>.
useDisabled()This hook returns the accordion sections’s disabled value. This hook
must be within a child of <Section>.
useIsOpen()This hook returns the accordion sections’s isOpen value. This hook
must be within a child of <Section>.
MIT