react-a11y-select

A customizable select/dropdown react component with a focus on accessibility (a11y) and ease of use for developers. The goals of this project are:

• Simplicity. The component should be as simple to use as its native HTML counterpart
• Accessibility. The component should have accessibility compliance with full keyboard control.
• Minimal styling.

Note: this project isn't associated with the https://github.com/reactjs/react-a11y package/project - it's an unfortunate naming collision. (v_v)

Live Demo

http://mikedesjardins.net/react-a11y-select/

Installation

via npm

npm install react-a11y-select

Usage

Here is a very simple example for how to use the component:

import { Select, Option } from 'react-a11y-select'
import 'react-a11y-select/src/styles.css'
...

<Select>
  <Option value="apple">
    <img src="apple.png" role="presentation" />
    Apple
  </Option>
  <Option value="cherry">
     <img src="cherry.png" role="presentation" />
     Cherry
  </Option>
</Select>

This will render an unordered list styled as a dropdown/select box. Importantly, it will have all of the correct ARIA and role attributes to make it usable by screen readers, and it will respond as expected to keyboard input.

Props

The following properties are on the <Select> component:

• label - the ARIA label attribute for the component. Briefly describes the form field for screen readers. Either label or labelledBy are required.
• labelledBy - the ARIA labelledBy attribute for the compoent. Set to the ID of a <label> DOM element which briefly describes the form field to screen readers (note: this is likely going to be deprecated soon)
• placeholderText - what appears in the dropdown before a value is selected. Defaults to "Please choose..."
• indicator - Unicode character that is used for the arrow indicator in the component. Defaults to &#x25be which is rendered as ▾
• initialValue - The initial value for the dropdown.
• onChange - a handler that is called when the select box value changes. Passed the value that was selected.
• buttonId - a value for the id attribute associated with the button. Useful if you have a <label> element and want to set its for attribute to this component. If not provided, one is autogenerated.
• listId - a value for the id attribute of the element that represents the list of options. If not provided, one is autogenerated.

The following properties are available on the <Option> component:

• value - The value associated with the Option.
• label - An ARIA label that assisted technologies can use in place to interpret the content of the option. Defaults to the value.
• disabled - If present, sets a disabled class and ignores onClick and onMouseOver events.

This is very much a work-in-progress

There's still a lot more to do on this project and most of it is in flux. It needs more tests, more features, more everything. Even when it's finished, it will probably be most valuable as a "demonstration" component to serve as inspiration for your own work. The props and API are subject to change. Here's a list of my TODOs:

• More tests. I'd love to take the ARIA best practices document (https://www.w3.org/TR/wai-aria-practices/#menubutton) and turn it into unit tests.
• Use Flow (or Typescript?) for typechecking.
• An <OptGroup> element would be nice, along with Separators.
• Need to record a screencast of the screen reader in action.
• Need to look at selecting a letter jumping in the list.
• Add other callbacks?

See this project's Github issues for other stuff.

Was this project not quite what you were looking for?

Check out David Clark's awesome aria menubutton project: https://github.com/davidtheclark/react-aria-menubutton It's another implementation of a React dropdown component where web accessibility is a primary goal.

Also take a look at Kent C. Dodd's Downshift project in Paypal's repo: https://github.com/paypal/downshift It's a far more robust and customizable set of tools for building your own accessible select components, and uses the somewhat less common (but far more flexible) solution of requiring developers to implement their own render methods.

I haven't personally used either of the above libraries in a project (yet), but they both look fantastic and might be just what you need!

License

MIT