Skip to content

Latest commit

 

History

History
executable file
·
239 lines (188 loc) · 15.5 KB

README.md

File metadata and controls

executable file
·
239 lines (188 loc) · 15.5 KB
Raw

<Accordion>

Bundlephobia Types Code coverage Build status NPM Version MIT License 

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