@accessible/accordion

---

<Accordion>

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.

Features

• Style-agnostic You can use this component with the styling library of your choice. It works with CSS-in-JS, SASS, plain CSS, plain style objects, anything!
• a11y/aria-compliant This component works with screen readers out of the box and manages focus for you.

Quick Start

Check out the example on CodeSandbox

import {Accordion, Section, Trigger, Panel} from '@accessible/accordion'

const Component = () => (
  <Accordion defaultOpen={0}>
    <Section>
      <h3>
        <Trigger>
          <button>Section 1</button>
        </Trigger>
      </h3>
      <Panel>
        <div className="panel">Section 1 content</div>
      </Panel>
    </Section>

    <Section>
      <h3>
        <Trigger>
          <button>Section 2</button>
        </Trigger>
      </h3>
      <Panel>
        <div className="panel">Section 2 content</div>
      </Panel>
    </Section>
  </Accordion>
)

API

Components

Component	Description
<Accordion>	This component creates the context for your accordion section and contains some configuration options.
<Section>	This component creates the context for the accordion panel and trigger contained in this section. It must be a direct descendent of <Accordion>.
<Trigger>	This component clones any React element and turns it into a accordion trigger that controls the visible state of the panel.
<Panel>	This component clones any React element and turns it into a accordion panel.
<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()	This hook returns the value of the accordion's AccordionContext object.
useSection()	This hook returns the value of the accordion <Section>'s SectionContext object.
useControls()	This hook returns the accordion <Section>'s open, close, and toggle functions.
useDisabled()	This hook returns the accordion <Section>'s disabled value.
useIsOpen()	This hook returns the accordion <Section>'s isOpen value.

<Accordion>

This component creates the context for your accordion section and contains some configuration options. <Section>s are the only type of children allowed.

Props

Prop	Type	Default	Required?	Description
defaultOpen	number | number[]	undefined	No	The section by index (or sections if allowMultipleOpen) you want opened by default.
open	number | number[]	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	(opened: number | number[]) => void	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>

This component creates the context for the accordion panel and trigger contained in this section. It must be a direct descendent of <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	React.ReactNode | ((context: SectionContextValue) => React.ReactNode)	undefined	Yes	Sections must include a <Trigger> and a 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 of the <Panel>. It must be a child of <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 be a child of <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. It must be a child of <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. This hook must be within a child of <Accordion>.

AccordionContextValue

interface AccordionContextValue {
  // DOM references to the accordion sections
  sections: (HTMLElement | undefined)[]
  // Registers a new accordion section
  registerSection: (index: number, trigger: HTMLElement) => () => void
  // The indexes of the open sections
  opened: number[]
  // Opens a section
  open: (section: number | undefined) => void
  // Closes a section
  close: (section: number | undefined) => void
  // Returns true if a section is open
  isOpen: (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>.

SectionContextValue

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>.

LICENSE

MIT