The Select Component for React.js
Clone or download
gwyneplaine Merge pull request #3059 from JedWatson/v2.1.0-release-notes
πŸŽ‰πŸŽ‰πŸŽ‰ changelog for v2.1.0
Latest commit 0fcc42d Sep 21, 2018
Permalink
Failed to load latest commit information.
.circleci Updating CircleCI docker container for cypress May 9, 2018
.github update contributing md Jul 23, 2018
cypress update cypress tests Jul 3, 2018
docs pass previously moved menu props from menuplacer back into menu Sep 21, 2018
flow-typed/npm inital test cases with jest-in-case Mar 14, 2018
src Merge pull request #3058 from JedWatson/revert-opinionated-neutral-co… Sep 21, 2018
typings Add prop definitions and API docs Mar 14, 2018
.TODO.md Updating TODO Apr 25, 2018
.babelrc Replacing glam with emotion Apr 24, 2018
.browserslistrc Fixing browserslistrc, thanks @jamiebuilds Apr 25, 2018
.coveralls.yml Update links and API to JedWatson/react-select Aug 9, 2015
.editorconfig Adding changes from #2559 Apr 26, 2018
.eslintignore Fixing linter issues Mar 20, 2018
.eslintrc.js Replacing glam with emotion Apr 24, 2018
.flowconfig Flow should ignore dist/ Apr 23, 2018
.gitignore Adding yarn.lock for netlify Apr 20, 2018
.nvmrc Adding sweet-changelogs config Jan 5, 2018
.nycrc coveraged configuration fixed, contrb document edited Sep 5, 2017
.prettierignore Stopping prettier from formatting package.json Apr 12, 2018
.prettierrc.js Adding .prettierrc.js Jan 18, 2018
.sweet-changelogs.js Adding sweet-changelogs config Jan 5, 2018
HISTORY.md Update HISTORY.md Sep 21, 2018
LICENSE Updating copyright for 2018 Jan 7, 2018
README.md Improved documentation clarity when CSS styling using `classNamePrefix` Sep 11, 2018
cypress.json fix tests / test route & add some delight Mar 2, 2018
enzymeAdapter.setup.js added a new line to enzyme adapter setup Mar 19, 2018
package-scripts.js Exporting Async, AsyncCreatable and Creatable in main bundle May 14, 2018
package.json revert-2933 Aug 16, 2018
rollup.config.js Prefer more descriptive esm word instead of es Jul 13, 2018
webpack.config.js Moving index.css into main docs folder Mar 20, 2018
yarn.lock [v2] Allow configuring the Theme object (#2839) Aug 20, 2018

README.md

NPM Build Status Coverage Status Supported by Thinkmill

React-Select

The Select control for React. Initially built for use in KeystoneJS.

See react-select.com for live demos and comprehensive docs.

Version 2 πŸŽ‰

React Select v2.0.0 is a complete rewrite, funded by Thinkmill and Atlassian. It represents a whole new approach to developing powerful React.js components that just work out of the box, while being extremely customisable.

Improvements include:

  • Flexible approach to data, with customisable functions
  • Extensible styling API with emotion
  • Component Injection API for complete control over the UI behaviour
  • Controllable state props and modular architecture
  • Long-requested features like option groups, portal support, animation, and more

If you're interested in the background, watch Jed's talk on React Select at ReactNYC in March 2018.

See our upgrade guide for a breakdown on how to upgrade from v1 to v2.

The old docs and examples will continue to be available at v1.react-select.com.

Installation and usage

The easiest way to use react-select is to install it from npm and build it into your app with Webpack.

yarn add react-select

Then use it in your app:

import React from 'react';
import Select from 'react-select';

const options = [
  { value: 'chocolate', label: 'Chocolate' },
  { value: 'strawberry', label: 'Strawberry' },
  { value: 'vanilla', label: 'Vanilla' }
];

class App extends React.Component {
  state = {
    selectedOption: null,
  }
  handleChange = (selectedOption) => {
    this.setState({ selectedOption });
    console.log(`Option selected:`, selectedOption);
  }
  render() {
    const { selectedOption } = this.state;

    return (
      <Select
        value={selectedOption}
        onChange={this.handleChange}
        options={options}
      />
    );
  }
}

Props

Common props you may want to specify include:

  • autoFocus - focus the control when it mounts
  • className - apply a className to the control
  • classNamePrefix - apply classNames to inner elements with the given prefix
  • isDisabled - disable the control
  • isMulti - allow the user to select multiple values
  • isSearchable - allow the user to search for matching options
  • name - generate an HTML input with this name, containing the current value
  • onChange - subscribe to change events
  • options - specify the options the user can select from
  • placeholder - change the text displayed when no option is selected
  • value - control the current value

See the props documentation for complete documentation on the props react-select supports.

Controllable Props

You can control the following props by providing values for them. If you don't, react-select will manage them for you.

  • value / onChange - specify the current value of the control
  • menuIsOpen / onMenuOpen / onMenuClose - control whether the menu is open
  • inputValue / onInputChange - control the value of the search input (changing this will update the available options)

If you don't provide these props, you can set the initial value of the state they control:

  • defaultValue - set the initial value of the control
  • defaultMenuIsOpen - set the initial open value of the menu
  • defaultInputValue - set the initial value of the search input

Methods

React-select exposes two public methods:

  • focus() - focus the control programatically
  • blur() - blur the control programatically

Customisation

Check the docs for more information on:

Thanks

Thank you to everyone who has contributed to this project. It's been a wild ride.

If you like React Select, you should follow me on twitter

Shout out to Joss Mackison, Charles Lee, Ben Conolly, Dave Brotherstone, Brian Vaughn, and the Atlassian Design System team ❀️

License

MIT Licensed. Copyright (c) Jed Watson 2018.