react-select Documentation

Technical Documentation: JedWatson/react-select

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

React-Select

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

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

react-select is funded by Thinkmill and Atlassian.
We are an open source project that is continuously supported by the community.

React Select helps you develop powerful select components that just work out of the box, without stopping you from customising the parts that are important to you.

For the story behind this component, watch Jed's talk at React Conf 2019 - building React Select

Features 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

Using an older version? Copy Chapter

• v3, v4, and v5 upgrade guide
• v2 upgrade guide
• React Select v1 documentation and examples are 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, { useState } from 'react';
import Select from 'react-select';

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

export default function App() {
  const [selectedOption, setSelectedOption] = useState(null);

  return (
    <div className="App">
      <Select
        defaultValue={selectedOption}
        onChange={setSelectedOption}
        options={options}
      />
    </div>
  );
}

Props Copy Chapter

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
• noOptionsMessage - ({ inputValue: string }) => string | null - Text to display when there are no options
• value - control the current value

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

Controllable Props Copy Chapter

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 Copy Chapter

React-select exposes two public methods:

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

Customisation Copy Chapter

Check the docs for more information on:

• Customising the styles
• Using custom components
• Using the built-in animated components
• Creating an async select
• Allowing users to create new options
• Advanced use-cases
• TypeScript guide

TypeScript Copy Chapter

The v5 release represents a rewrite from JavaScript to TypeScript. The types for v4 and earlier releases are available at @types. See the TypeScript guide for how to use the types starting with v5.

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, Tom Walker, Nathan Bierema, Eric Bonow, Emma Hamilton, Dave Brotherstone, Brian Vaughn, and the Atlassian Design System team who along with many other contributors have made this possible ❤️

License Copy Chapter

MIT Licensed. Copyright (c) Jed Watson 2022.

Overview (`.changeset/README.md`) Copy Section

Changesets

Hello and welcome! This folder has been automatically generated by @changesets/cli, a build tool that works with bolt to help you release components from a mono-repository. You can find the full documentation for it here

To help you get started though, here are some things you should know about this folder:

Changesets are automatically generated Copy Chapter

Changesets are generated by the yarn changeset or npx changeset command. As long as you are following a changeset release flow, you shouldn't have any problems.

Each changeset is its own folder Copy Chapter

We use hashes by default for these folder names to avoid collisions when generating them, but there's no harm that will come from renaming them.

Changesets are automatically removed Copy Chapter

When changeset bump or equivalent command is run, all the changeset folders are removed. This is so we only ever use a changeset once. This makes this a very bad place to store any other information.

Changesets come in two parts Copy Chapter

You should treat these parts quite differently:

• changes.md is a file you should feel free to edit as much as you want. It will be prepended to your changelog when you next run your version command.
• changes.json is a file that includes information about releases, what should be versioned by the version command. We strongly recommend against editing this directly, as you may make a new changeset that puts your bolt repository into an invalid state.

I want to edit the information in a `changes.json` - how do I do it safely? Copy Chapter

The best option is to make a new changeset using the changeset command, copy over the changes.md, then delete the old changeset.

Can I rename the folder for my changeset? Copy Chapter

Absolutely! We need unique hashes to make changesets play nicely with git, but changing your folder from our hash to your own name isn't going to cause any problems.

Can I manually delete changesets? Copy Chapter

You can, but you should be aware this will remove the intent to release communicated by the changeset, and should be done with caution.

Overview (`packages/react-select/README.md`) Copy Section

React-Select

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

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

React Select is 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.

For the story behind this component, watch Jed's talk at React Conf 2019 - building React Select

Features 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

Using an older version? Copy Chapter

• v3, v4, and v5 upgrade guide
• v2 upgrade guide
• React Select v1 documentation and examples are 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:

With React Component

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:`, this.state.selectedOption)
    );
  };
  render() {
    const { selectedOption } = this.state;

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

With React Hooks

import React, { useState } from 'react';
import Select from 'react-select';

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

export default function App() {
  const [selectedOption, setSelectedOption] = useState(null);

  return (
    <div className="App">
      <Select
        defaultValue={selectedOption}
        onChange={setSelectedOption}
        options={options}
      />
    </div>
  );
}

Props Copy Chapter

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
• noOptionsMessage - ({ inputValue: string }) => string | null - Text to display when there are no options
• value - control the current value

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

Controllable Props Copy Chapter

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 Copy Chapter

React-select exposes two public methods:

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

Customisation Copy Chapter

Check the docs for more information on:

• Customising the styles
• Using custom components
• Using the built-in animated components
• Creating an async select
• Allowing users to create new options
• Advanced use-cases
• TypeScript guide

TypeScript Copy Chapter

The v5 release represents a rewrite from JavaScript to TypeScript. The types for v4 and earlier releases are available at @types. See the TypeScript guide for how to use the types starting with v5.

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, Tom Walker, Nathan Bierema, Eric Bonow, Emma Hamilton, Dave Brotherstone, Brian Vaughn, and the Atlassian Design System team who along with many other contributors have made this possible ❤️

License Copy Chapter

MIT Licensed. Copyright (c) Jed Watson 2022.

CHANGELOG (`docs/CHANGELOG.md`) Copy Section

@react-select/docs

3.1.3 Copy Chapter

Patch Changes Copy Section

• 0773095f #5457 Thanks @nderkim! - Add classNames API and unstyled prop

• Updated dependencies [0773095f]:

  • react-select@undefined

3.1.2 Copy Chapter

Patch Changes Copy Section

• 0ca2d5ba #5431 Thanks @nderkim! - Change class components to functional components

• Updated dependencies [0ca2d5ba]:

  • react-select@undefined

3.1.1 Copy Chapter

Patch Changes Copy Section

• 638f5455 #4702 Thanks @Methuselah96! - The Option generic is no longer required to extend the OptionBase type

• Updated dependencies [10225290]:

• Updated dependencies [53f1972b]:

• Updated dependencies [b41f4ceb]:

• Updated dependencies [4b028829]:

• Updated dependencies [7fcec537]:

• Updated dependencies [ca2c0e5b]:

• Updated dependencies [9e82aadc]:

• Updated dependencies [638f5455]:

• Updated dependencies [23cea0b5]:

• Updated dependencies [ef87c3ac]:

  • react-select@undefined

3.1.1-beta.1 Copy Chapter

Patch Changes Copy Section

• 638f5455 #4702 Thanks @Methuselah96! - The Option generic is no longer required to extend the OptionBase type

• Updated dependencies [10225290]:

• Updated dependencies [53f1972b]:

• Updated dependencies [b41f4ceb]:

• Updated dependencies [7fcec537]:

• Updated dependencies [9e82aadc]:

• Updated dependencies [638f5455]:

  • react-select@undefined

3.1.1-beta.0 Copy Chapter

Patch Changes Copy Section

• Updated dependencies [4b028829]:
• Updated dependencies [ef87c3ac]:
  • react-select@undefined

3.1.0 Copy Chapter

Minor Changes Copy Section

• 2baf5a9d #4414 Thanks @ebonow! - Add ariaLiveMessages prop for internationalization and other customisations

Patch Changes Copy Section

• Updated dependencies [2ffed9c6]:
• Updated dependencies [c955415c]:
• Updated dependencies [3ca22b2f]:
• Updated dependencies [dce3863f]:
• Updated dependencies [2baf5a9d]:
• Updated dependencies [7cdb8a6b]:
• Updated dependencies [ec7c0728]:
  • react-select@undefined

3.0.1 Copy Chapter

Patch Changes Copy Section

• a016c878 #4420 Thanks @Methuselah96! - Bump dependency on @babel/runtime in order to fix compatibility issues with Webpack 5

• 0dbf0438 #4387 Thanks @ebonow! - Update example for MultiSelectSort to prevent dragging on multiValueRemove component #4387

• Updated dependencies [f600d13f]:

• Updated dependencies [b5f9b0c5]:

• Updated dependencies [a016c878]:

• Updated dependencies [19b76342]:

• Updated dependencies [10b5f5a5]:

  • react-select@undefined

3.0.0 Copy Chapter

Major Changes Copy Section

• 26b6325c #4283 Thanks @majgaard! - Upgrades Emotion dependency to v11.0.0

  BREAKING CHANGE: The NonceProvider component now requires a cacheKey prop that corresponds to the key for the Emotion cache.

Patch Changes Copy Section

• Updated dependencies [2d5496d5]:
• Updated dependencies [02050675]:
• Updated dependencies [26b6325c]:
• Updated dependencies [b2488bb5]:
  • react-select@undefined

2.4.6 Copy Chapter

Patch Changes Copy Section

• 7af1aafb #4295 Thanks @JedWatson! - Fix menuplacement context

• Updated dependencies [c8d74bd5]:

• Updated dependencies [c8447f48]:

• Updated dependencies [7af1aafb]:

• Updated dependencies [32ad5c04]:

• Updated dependencies [6af14fbb]:

• Updated dependencies [0eb1ef96]:

• Updated dependencies [ad608c8f]:

  • react-select@undefined

2.4.5 Copy Chapter

• Updated dependencies [9ad152b]:
  • [email protected]

Package.Json (`docs/package.json`) Copy Section

{
"name": "@react-select/docs",
"private": true,
"version": "3.1.3",
"main": "dist/docs.cjs.js",
"author": "Jed Watson",
"license": "MIT",
"dependencies": {
"@atlaskit/button": "^15.1.4",
"@atlaskit/icon": "^11.0.1",
"@atlaskit/modal-dialog": "^11.2.5",
"@atlaskit/spinner": "^15.0.6",
"@atlaskit/tooltip": "^17.1.2",
"@babel/runtime": "^7.12.0",
"@emotion/react": "^11.8.1",
"@magical-types/convert-type": "^0.1.4",
"@magical-types/pretty": "^0.3.5",
"@magical-types/serialization": "^0.2.1",
"@magical-types/types": "^0.1.2",
"@types/chroma-js": "^1.4.3",
"@types/node-fetch": "^2.5.8",
"@types/raf-schd": "^4.0.0",
"@types/react-codesandboxer": "^3.1.0",
"@types/react-helmet": "^5.0.16",
"@types/react-markings": "^1.3.0",
"@types/react-node-resolver": "^2.0.0",
"@types/react-router-dom": "^4.3.5",
"@types/react-syntax-highlighter": "^0.0.8",
"@types/webpack": "^4.41.26",
"@types/webpack-dev-server": "^3.11.1",
"babel-plugin-macros": "^3.0.1",
"chroma-js": "^2.4.2",
"chrono-node": "^2.1.11",
"clean-webpack-plugin": "^3.0.0",
"codesandboxer": "^0.1.1",
"fork-ts-checker-webpack-plugin": "^6.1.0",
"html-webpack-plugin": "^3.2.0",
"moment": "^2.29.4",
"raf-schd": "^4.0.3",
"raw-loader": "^2.0.0",
"react": "^16.13.0",
"react-codesandboxer": "^3.1.5",
"react-dom": "^16.13.0",
"react-helmet": "^5.2.0",
"react-markings": "^1.3.0",
"react-router-dom": "^4.2.2",
"react-select": "^5.7.0",
"react-sortable-hoc": "^1.9.1",
"react-syntax-highlighter": "^7.0.1",
"style-loader": "^0.23.1",
"styled-components": "^4.4.1",
"ts-node": "^9.1.1",
"unfetch": "^4.2.0",
"webpack": "^4.30.0",
"webpack-cli": "^4.10.0",
"webpack-dev-server": "^3.3.1"
},
"scripts": {
"site-prebuild": "node ./generate-magical-types/generate && node ./generate-magical-types/serialize",
"start": "yarn site-prebuild && webpack serve --progress",
"start:test": "NODE_ENV=test yarn site-prebuild && webpack serve --progress",
"build:docs": "rimraf docs/dist && yarn site-prebuild && webpack --progress --mode production"
}
}

Tsconfig.Json (`docs/tsconfig.json`) Copy Section

{
"compilerOptions": {
"target": "es6",
"module": "commonjs",
"jsx": "react",
"noEmit": true,
"strict": true,
"esModuleInterop": true,
"forceConsistentCasingInFileNames": true,
"resolveJsonModule": true
}
}

Generate Magical Types Package.Json (`docs/generate-magical-types/package.json`) Copy Section

{
"name": "@react-select/generate-magical-types",
"main": "dist/generate-magical-types.cjs.js",
"exports": {
"./generate": {
"module": "./generate/dist/react-select-generate-magical-types-generate.esm.js",
"import": "./generate/dist/react-select-generate-magical-types-generate.cjs.mjs",
"default": "./generate/dist/react-select-generate-magical-types-generate.cjs.js"
},
"./serialize": {
"module": "./serialize/dist/react-select-generate-magical-types-serialize.esm.js",
"import": "./serialize/dist/react-select-generate-magical-types-serialize.cjs.mjs",
"default": "./serialize/dist/react-select-generate-magical-types-serialize.cjs.js"
},
"./package.json": "./package.json"
},
"//": "these deps aren't real, they're just to appease preconstruct",
"dependencies": {
"@babel/runtime": "",
"@magical-types/convert-type": "",
"@magical-types/serialization": "",
"ts-morph": "",
"fs-extra": "",
"flatted": ""
},
"preconstruct": {
"entrypoints": [
"generate.ts",
"serialize.ts"
]
}
}

Generate Magical Types Generate Package.Json (`docs/generate-magical-types/generate/package.json`) Copy Section

{
"main": "dist/react-select-generate-magical-types-generate.cjs.js",
"module": "dist/react-select-generate-magical-types-generate.esm.js"
}

Generate Magical Types Serialize Package.Json (`docs/generate-magical-types/serialize/package.json`) Copy Section

{
"main": "dist/react-select-generate-magical-types-serialize.cjs.js",
"module": "dist/react-select-generate-magical-types-serialize.esm.js"
}

--- METRICS ---

• Files Extracted: 9
• Estimated Token Budget: ~5886 tokens
• Canonical Reference: https://codewiki.google/github.com/JedWatson/react-select