react-aria-accordion
v1.0.7TypeScript
React accordion component that follows WAI-ARIA practices
1.5K/weekUpdated 3 years agoMITUnpacked: 52.8 KB
Published by Kenny Gray
npm install react-aria-accordionReact Aria Accordion
This accordion component aims to follow the guidelines set out in the WAI-ARIA Authoring Practices 1.1
and uses the render props pattern to be as flexible
as possible.
It is purposefully missing the ability for a section to be auto collapsed on expanding another. Read Design decisions for more information.
Demo
Table of contents
- Installation
- Example usage
- Using \
- API
- \
- \
- \
- \
- initialiseForSsr
- Design decisions
- Technical decisions
- Contributors
Installation
``
npm install react-aria-accordion
Example usage
Given the flexible nature of the component it would be best to wrap each component and style them as is appropriate for your use case.
`jsx
// Accordion/Accordion
import Accordion from 'react-aria-accordion';
const MyAccordion = ({ children, ...rest }) => (
{() => {children}}
);
export default MyAccordion;
// Accordion/Section
import { Section } from 'react-aria-accordion';
const MySection = ({ onToggle, defaultExpanded, children }) => (
{({ getSectionProps }) => {children}}
);
export default MySection;
// Accordion/Header
import { Header } from 'react-aria-accordion';
// Using native html elements
const MyHeader = ({ title }) => (
{({ getButtonToggleProps }) => (
)}
);
// Using custom html elements
const MyHeader = ({ title }) => (
{({ getHeadingProps, getElementToggleProps }) => (
{title}
)}
);
export default Header;
// Accordion/Panel
import { Panel } from 'react-aria-accordion';
const MyPanel = ({ children }) => (
{({ getPanelProps }) => (
{children}
)}
);
export default MyPanel;
// Accordion/index
export { default } from './Accordion';
export { default as Section } from './Section';
export { default as Header } from './Header';
export { default as Panel } from './Panel';
`
This would allow the following:
`jsx
import Accordion, { Section, Header, Panel } from './Accordion';
onToggle={
(nextExpanded) => console.log(First section is ${nextExpanded ? 'expanded' : 'collapsed'})
}
>
{listOfNames}
{listOfContactDetails}
{other}
`
$3
An additional initialiseForSsr function is required when using SSR so that the DOM matches when using client hydration:
`jsx
import { renderToString } from 'react-dom/server';
import { initialiseForSsr } from 'react-aria-accordion';
initialiseForSsr();
renderToString(
`
Using \
The title for the accordion section must be wrapped in exactly one button and one heading. The following 2 examples offer the same semantics. Where possible use native html elements.
`jsx
const header = (
{({ getButtonToggleProps }) => (
)}
);
const header = (
{({ getHeadingProps, getElementToggleProps }) => (
Title
)}
);
`
If you want to include a menu next to the title, then make sure the menu is not inside the heading element.
`jsx`
const header = (
{({ getButtonToggleProps }) => (
)}
);
API
$3
#### children
> function({}) | _required_
This is called with an object.
| Property | Type | Description |
|-----------------------|--------------|-------------------------|
| expandAllSections | function() | Expands all sections. |collapseAllSections
| | function() | Collapses all sections. |
$3
#### defaultExpanded
> boolean | defaults to false
This is the initial expanded value.
#### expanded
> boolean | control prop
#### onToggle
> function(nextExpanded: boolean) | defaults to undefined
#### children
> function({}) | _required_
This is called with an object.
| Property | Type | Description |
|-------------------|---------------------------|---------------------------------------------------------------|
| getSectionProps | function(props: object) | Returns the props you should apply to the element you render. |expanded
| | boolean | The expanded state of the section. |
$3
#### disabled
> boolean | defaults to false
#### headingLevel
> number | defaults to 1
#### children
> function({}) | _required_
This is called with an object.
| Property | Type | Description |
|-------------------------|---------------------------|--------------------------------------------------------------------------------------------------|
| getHeadingProps | function(props: object) | Returns the props you should apply to the heading element you render when not using . |getButtonToggleProps
| | function(props: object) | Returns the props you should apply to the toggle element you render when using . |getElementToggleProps
| | function(props: object) | Returns the props you should apply to the toggle element you render when not using . |expanded
| | boolean | The expanded state of the section. |
$3
#### children
> function({}) | _required_
This is called with an object.
| Property | Type | Description |
|-----------------|---------------------------|---------------------------------------------------------------|
| getPanelProps | function(props: object) | Returns the props you should apply to the element you render. |expanded
| | boolean | The expanded state of the section. |
$3
> function()
See Server Side Rendering (SSR) for more details.
Design decisions
$3
The aim of this component is to be used in projects to help developers feel confident they are
making their websites as accessible as possible using relevant aria-* properties.
Automatic collapsing of sections can disorientate some users, particularly if scroll behaviour is
also associated. For example, if a user is using magnification software they may not realise that
expanding one section has collapsed another.
Data presented within a section may be comparable with another, therefore having more than one
section expanded at a time may be a useful feature for your users.
Collapsing and expanding multiple sections manually may make your website difficult to use, so
this component provides the functionality to collapse and expand all sections at once. Given this
behaviour will need to be triggered by a user there are less usability concerns.
Technical decisions
$3
The reason the same render prop is available is so that it's possible to wrap each component as
shown in Example usage without having to pass your own expanded prop to Header
and .
$3
You may think that using a lifecycle method like componentWillMount in would
suffice, however it wouldn't cope with the following scenario:
`jsx`
{showSection ?
If showSection starts as false and switches to true later, then componenetWillMount will` would be a burden on the developer.
fire for Section B, leaving the accordion no ability to know the ordering of the sections. Having
to manually specify the order of a
Contributors
Thanks goes to these wonderful people (emoji key):
|
Kenneth Gray
💻 📖 ⚠️ 💡 |
Koji Wakayama
💻 |
| :---: | :---: |
This project follows the all-contributors specification. Contributions of any kind are welcome!