Skip to content
A customisable, touchable, React select / multi-select form control. Built with keyboard and screen reader accessibility in mind
Branch: master
Clone or download
Latest commit af4736f Mar 16, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
__mocks__ Use Jest instead of Mocha - easier to look after Aug 2, 2018
auto exit `npm run deploy` if not on master branch Mar 16, 2019
demo Deploy to gh-pages... Mar 16, 2019
dist Deploy to gh-pages... Mar 16, 2019
src Update docs Mar 16, 2019
.babelrc Add optHeader prop for showing a header before an option. An optgroup… Oct 8, 2018
.editorconfig initial commit Feb 9, 2017
.eslintrc
.gitignore Update coverage tool Feb 12, 2017
.npmignore
.nvmrc
.prettierrc.js Add prettier Aug 20, 2018
.travis.yml Update node version for build process, and run yarn update Jun 28, 2018
LICENSE Update to MIT license May 23, 2017
README.md
README_INTERACTION_TESTS.md Update docs Oct 30, 2017
index.d.ts
index.html Code formatting Apr 15, 2018
package.json exit `npm run deploy` if not on master branch Mar 16, 2019
webpack.config.demo.js Update docs Jul 30, 2018
webpack.config.react-responsive-select.js Convert webpack config output.libraryTarget from "umd" to "commonjs2"… May 30, 2018
yarn.lock Remove unused dependencies Oct 3, 2018

README.md

React Responsive Select

Build status

A customisable, touchable, React single-select / multi-select form control.

Built with keyboard and screen reader accessibility in mind.

Features

  • Single and Multi select modes
  • Accessible WAI ARIA compliance
  • Touch friendly
  • Keyboard friendly
  • Similar interaction experience across platforms
  • Custom label rendering
  • Custom option markup
  • Option headers
  • Mimics keyboard functionality where possible (sans multiselect)
  • Easy slot-in to your design system
  • No global styling

Demo

https://benbowes.github.io/react-responsive-select/demo/

Codepen

Screen reader demo

Voice over demo gif


Getting started

Install the dependency - https://www.npmjs.com/package/react-responsive-select

npm install react-responsive-select -D

Example usage:

import React from 'react';
import ReactResponsiveSelect from 'react-responsive-select';

const onChange = (newValue) => console.log('onChange', newValue);
const onSubmit = () => console.log('onSubmit');

const Form = () => (
  <form>
    <ReactResponsiveSelect
      name="make"
      options={[
        { text: 'Any', value: 'null' },
        { text: 'Oldsmobile', value: 'oldsmobile', markup: <span>Oldsmobile</span> },
        { text: 'Ford', value: 'ford', markup: <span>Ford</span> }
      ]}
      selectedValue="oldsmobile"
      onSubmit={onSubmit}
      onChange={onChange}
      caretIcon={<CaretIcon />}
    />
  </form>
);

A more detailed usage example can be found here: https://github.com/benbowes/react-responsive-select/blob/master/demo/src/index.js


Styling

The CSS in react-responsive-select/dist/ReactResponsiveSelect.css is plain css. Use as-is, or alter it to meet your projects needs.

You can either include the base styles into your project via an import, or copy paste it's contents into your theming solution - be it css modules, sass/less, css-in-js. The styles are self contained (not global).

The class-names themselves are not configurable.


API

Single Select

prop type description
name (required) String The name to send with the selected option value(s) on form submit
options (required) Array of objects

Array of shape:

{ text: "Fiat", value: "fiat", markup: <span>Fiat</span>, disabled: true; }

or

{ text: 'Cars', optHeader: true }


text: (Required) display value for the select and the default for the option label

value: (Required) value that is submitted

markup: (Optional) JSX markup used as the option label. Allows for the use of badges and icons...

optHeader: (Optional) Will display an option header when present. Use with a text property

disabled: (Optional) disable option - option cannot be selected and is greyed

Note: text is used as the option label when markup is not present

onSubmit Function Some function that submits your form
onChange Function

Listen for changes on selected option change

returns { altered: true||false, name: select.name, value: option.value, text: option.text }

Note: altered signifies whether a select has been changed from it's original value.

onBlur Function

Listen for blur when select loses focus

returns { altered: true||false, name: select.name, value: option.value, text: option.text }

Note: altered signifies whether a select has been changed from it's original value.

caretIcon JSX Add a dropdown icon by using JSX markup
selectedValue String Pre-select an option with this value - should match an existing option.value, or if omitted the first item will be selected
prefix String Prefix for the select label
disabled Boolean Disables the select control
noSelectionLabel string A custom label to be used when nothing is selected. When used, the first option is not automatically selected
customLabelRenderer Function

Allows you to format your own select label

The customLabelRenderer function returns an option object e.g. { name: select.name, value: option.value, text: option.text }

To use this feature you need to return some JSX; using values from the above object to create your own custom label.

See the example in the [singleselect demo](https://github.com/benbowes/react-responsive-select/blob/master/demo/src/index.js#L144).

Multi Select

Same as Single Select API but with the following amendments

multiselect Boolean Makes the select control handle multiple selections. Check the implementation example here: https://benbowes.github.io/react-responsive-select/demo/
selectedValues Array of String values Pre-select several options with this value - should match against an existing option.value, or if omitted, the first item will be selected. e.g. selectedValues={['mazda','ford']}
customLabelRenderer Function

Allows you to format your own select label

The customLabelRenderer function returns an array option objects e.g. [{ name: select.name, value: option.value, text: option.text }]

To use this feature you need to return some JSX; using values from the above object to create your own custom label.

See the example in the [multiselect demo](https://github.com/benbowes/react-responsive-select/blob/master/demo/src/index.js#L589-L591).

noSelectionLabel string A custom label to be used when nothing is selected. When used, the first option is not automatically selected
onChange Function

Listen for changes in selection

returns { altered: true||false, options: [{name: select.name, value: option.value, text: option.text }]}

Note: altered signifies whether a select has been changed from it's original value.

onBlur Function

Listen for blur when select loses focus

returns { altered: true||false, options: [{name: select.name, value: option.value, text: option.text }]}

Note: altered signifies whether a select has been changed from it's original value.

CDN

JS: https://unpkg.com/react-responsive-select@latest/dist/ReactResponsiveSelect.js

CSS: https://unpkg.com/react-responsive-select@latest/dist/ReactResponsiveSelect.css

The Codepen examples are consuming react-responsive-select via CDN if you'd like a guide.

Babel Preset Env Targets

{
  "chrome": "62",
  "android": "4.2",
  "edge": "13",
  "firefox": "56",
  "ie": "11",
  "ios": "10",
  "safari": "10"
}

React Responsive Select 2.x => 3.x upgrade guide

See: https://github.com/benbowes/react-responsive-select/releases/tag/3.0.0

React Responsive Select 3.x => 4.x

Upgraded from React 15.x to React 16.x

Interaction Tests

For information about how this select control works on desktop and mobile see the Interaction tests readme README_INTERACTION_TESTS.md

You can’t perform that action at this time.