The Select Component for React.js

Jed Watson

Last update: Jan 3, 2023

Related tags

React react-select

Overview

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?

v2 to v3 upgrade guide
v1 to 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

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

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

License

MIT Licensed. Copyright (c) Jed Watson 2021.

Comments

React-select is slow when you have more than 1000 items
Low performance on large sets of options

React-select slows down when you have a huge array of data. Mouse

FPS drops so low on mouseover, that i can barely use it. In my real case, where i have 1010 items, which i need to show(and i can't load them as user types) - i cannot do anything at all.

You can find a simple example in codesandbox.

https://codesandbox.io/s/q8l6xnvz7w

[Violation] 'mouseover' handler took 346ms [Violation] 'mouseover' handler took 184ms [Violation] 'mouseover' handler took 197ms [Violation] 'mouseover' handler took 172ms [Violation] 'mouseover' handler took 161ms [Violation] 'mouseover' handler took 150ms [Violation] 'mouseover' handler took 167ms [Violation] 'mouseover' handler took 172ms [Violation] 'mouseover' handler took 156ms [Violation] 'mouseover' handler took 166ms

React-select version: 2.1.0
issue/reviewed
opened by VladimirMilenko 82
feat(pagination): add async pagination

This checks the first box in this list for v1.0.0 and closes #644

This adds a new pagination prop to the Select.Aync component. It is a boolean which is false by default (false: things act as they did before it was added). When pagination is true loadOptions is given an additional argument; page. page tells the user's loadOptions function which page to load (they can use to when building their request). Additional page results are appended to the options list. Changing the input value will reset the page back to 1. loadOptions is called when the user scrolls to the bottom of the menu list, trigger the next page of results to be appended. Caching is used! (Cache all the things!). If a user scrolls down enough to load additional pages, then changes the input (triggering new requests), then enters the original input, all of the pages for the original input will be loaded back and when the user scroll to the bottom again, it will pick up on the page it left off on.

Documentation has been updated to reflect the new prop and how it affects loadOptions' signature.

EDIT:

opened by TheSharpieOne 68
positioning the component in containers that have `overflow: scroll;`

I recently ran into this issue when using react-select components in a modal. For mobile the contents of the modal are scrollable. In this particular case, the Select was at the bottom of the content. Activating the Select made the container overflow and scrollable.

Maybe the container notion of http://react-bootstrap.github.io/react-overlays/examples/ might make sense? Alternatively, maybe make use of https://github.com/souporserious/react-tether?
pr/needs-review

opened by ksmth 64
Dropdown remains fixed in place and doesn't scroll with parent container

This issue is a round-up of multiple past issues documenting the same bug. Feel free to check out the linked issues below for more information. This issue is the source of truth going forward to investigate the issue, report findings, and implement a bug fix.

Issue:

Dropdown remains fixed in place and doesn't scroll with parent container.

The commit responsible for this issue is located here - https://github.com/JedWatson/react-select/commit/691a01171969da89e20097f9d603651bb18a8510

Version v3.0.4 does not have this bug however the latest release v3.1.0 does.

Issues:

https://github.com/JedWatson/react-select/issues/4554 https://github.com/JedWatson/react-select/issues/4020 https://github.com/JedWatson/react-select/issues/4052 https://github.com/JedWatson/react-select/issues/3734 https://github.com/JedWatson/react-select/issues/4085 https://github.com/JedWatson/react-select/issues/3929 https://github.com/JedWatson/react-select/issues/3349 https://github.com/JedWatson/react-select/issues/3646

Examples:

https://codesandbox.io/s/react-select-v3-sandbox-forked-lgkms https://codesandbox.io/s/compassionate-cookies-85j2n https://codesandbox.io/s/react-select-v3-sandbox-kr5wf https://codesandbox.io/s/festive-dirac-izf5y https://codesandbox.io/s/react-codesandboxer-example-xy47y

If anyone would like to share any further information, please do so.
issue/bug-confirmed issue/reviewed menu-bug

opened by bladey 60
Implemented allowCreate and more flexible add item on comma functionality

I took the pull request #660 (which relates to #658 and #586) and re-did it as this is a huge show stopper for me on using this library and that implementation seemed a bit broken (and the 0.9.1 does not have some of the functionality that I also need the 1.0.0-beta does).

This adds back in the allowCreate functionality with the tests reworked to pass (I also fixed an existing failing test as it seemed to be using the old setPropselectorChild method instead of setPropsForChild)

UPDATE:

I added another commit here to add a more flexible solution to the old add item on comma when allowCreate and mutli are enabled. My solution allows you to specific the keyCode to use to add a new item (set with the addItemOnKeyCode prop). While comma is pretty common, it is not always the best option and making it flexible like this it not that much difference in the implementation. This also allows you to turn off this feature which was not possible in the older implementation which i think is not completely uncommon. By default the addItemOnKeyCode prop is set to null so that the user need to explicitly enable this functionality.

Also, I have no idea what the @coveralls messages mean. I did run coverage reports before and after and the coverage did not go down after my src / test updates (they actually went up on 1 or 2 src files but only marginally).

If I could get an update if this will be an acceptable PR (or if any changes are needed to get this merged) and included into a npm tagged beta release relatively soon that would be great. Without these changes, using this library is a show stopper. Since 0.9.1 is also missing functionality the 1.x beta version has, using that version is also a show stopper. If these features are not going to be able to be consumable through npm relatively soon, I am going to have to publish my own version to be able to move forward with this library which I would prefer not to do.

opened by ryanzec 60
Z-Index Problems?

I had this problem with a default install of react-select ? I can't seem to figure it out, I have spent hours on this. It appears near impossible to get the dropdown to be above everything... perhaps some sort of portal solution should be used for this ?

opened by bradennapier 56
Control opening direction up/down

Hi! Is there a way to control the opening direction programmatically? kinda like the native select tag behavior, opens up or down (when there is not enough space for the dropdown to open up ). thanks!

opened by BenGedi 55
onChange returns the selected value, not the complete event
onChange simply returns the new value and label and not the whole event.

I understand we can use the hidden input field to fire an onChange but this does not happen automatically and while we can manually fire an onChange for hidden input field, we can also wrap an event around the Select. Here is how I am doing it following #520:

<Select name="form-field-name" value={val} options={options} onChange={(val)=> {onChangeFunc({target: { name:'revision_id', value: val.value }})}} />

Creating an object myself and passing it to my onChange handler. Is this the right way to do it or you can suggest a better way around it?
opened by OsamaShabrez 46

Debouncing support

Hi there, I was wondering there is a way to "debounce" async option loading with react-select. Currently, I'm seeing queries like this:

I would like react-select to only query after a 250ms typing pause. What do I need to do to make react-select do this? I have tried wrapping my function in a setTimeout, but that does not appear to do anything:

  taxons (input, callback) {
    setTimeout(function () {
      $.ajax({
        url: '/api/v2/taxons/search',
        dataType: 'json',
        cache: false,
        data: { name: input },
        success: function (response) {
          var options = response.data.map(function(taxon, index) {
            return (
              { value: taxon.id, label: taxon.attributes.tree_name }
            );
          });

          callback(null, {
            options: options
          })
        }
      })
    }, 250)
  }

opened by radar 44

Support inline-block / sizes

react-select only seems to work as a full-width block component. It would be nice if it would also support use as an inline-block component (like a standard <select>) with either an auto-calculated width or a specified width.

opened by dantman 40
Rewrite / 1.0
I'm midway through a massive rewrite of this library and wanted to open an issue so it's more visible. There will be several breaking changes to the API, all for the better.

WIP is visible on the rebuild branch.

Aside from how we're bundling lib and dist files (which won't change for now), it basically addresses all the things that @brianreavis raised in #227.

I've been trying to split Select up into more granular components as suggested by @bruderstein in #396, but it's not obvious how to do this while also cleaning everything up and preserving a simple API so that can probably be the focus of another major version down the track.

The big improvements include:

Everything is simpler (I'm nearly done and the source code is only 60% of the size of the last version)

No more timeouts or weird handlers, the restructuring has let me make everything more straight-forward

The options array is no longer preprocessed into state, just retrieved from props

The values array is now initialised in the Options array during render, and not stored in state, which along with the change to options makes the component more reliable and fixes issues with props not updating correctly

The component no longer stores its own value in state (ever) - it needs to be passed as a prop and handled with onChange.

Complex values are now enabled by default (so you're passed the option object, not its value); you can enable the legacy mode with a prop

The Value and Option components have been cleaned up as well for consistency

The hidden <input> field is now optional and the component is better suited to use in a rich React.js app than it was

You can disable options filtering to do the filtering externally with onInputChange

Accents on characters can now be ignored

The other major change is that the whole async options loading piece has been split out into its own Select.Async component, which wraps Select and passes most props through. This dramatically simplifies the select component itself, and plays nicely with the new "options and value are just props" changes. Props that were related to asyncOptions have also been moved to the new component.

Aside from the details of what's been changed, it just feels better to use, more solid. I don't have benchmarks to back this up, but it should be much faster too (and easier to optimise in subsequent versions)
opened by JedWatson 39
Fixes #4966 Async select: inputChange bug

This change fixes #4966

The bug presented when the options were loaded asynchronously with a callback using loadOptions and had cacheOptions: true.

I included both a fix and unit tests for this.

opened by feder240516 2
Multivalue menu focuses to first option on enter

Version react-select: 5.2.1

Issue is when I have enough options for the menu to scroll. The Menu works fine if i use the mouse but when i use my keyboard and navigate down and select by pressing Enter key. The focus of the option goes to first option. Is there a way to prevent this?
issue/bug-unconfirmed

opened by chrispobs 0

isMulti in AsyncSelect - typescript

Hi everyone, I have a problem, when I want to use AsyncSelect with isMulti={true} I see TS error

<AsyncSelect
      isMulti={true}
      cacheOptions={false}
      loadOptions={loadOptions}
      closeMenuOnSelect={true}
      formatOptionLabel={FormatOptionLabel}
      components={{ Control, MenuList }}
      styles={selectStyles}
      placeholder={placeholder}
      noOptionsMessage={noOptionsMessage}
      openMenuOnClick={false}
      onChange={selectedOptions => setValue(selectedOptions)}
      value={value}
      isDisabled={isDisabled}
      onKeyDown={e => e.key === 'Enter' && changeQuery()}
      inputValue={inputValue}
      onInputChange={(newValue, { action }) => action !== 'menu-close' && setInputValue(newValue)}
    />

(property) isMulti?: false | undefined
Support multiple selected options

Type 'true' is not assignable to type 'false'.ts(2322)

Someone has any idea for it?

I'm using: react-select: 5.7.0 typescript: 4.9.4 react: 18.2.0

issue/bug-unconfirmed

opened by wesolypl 1

Android Webview, Not clickable select box but able to click arrow

We are loading the web content in android web view. While clicking the react-select component in the input area it's not respond or clickable(Drop down options not showing) but we can able to click the arrow button.

Please anyone face this issue, let me know how to resolve this issue.

Version: 3.2.1
awaiting-author-response

opened by kumark86 3
Select is slow to render with many selected options
React select is slow to render and slows down other UI elements if it has many selected options.

Reproduction:

https://codesandbox.io/s/react-select-v5-sandbox-forked-b9dgvl?file=/example.js

If you toggle "Toggle other content" button, div appears ant disappears fast.

Clicking "Toggle select" already renders slow when Select appears.

Now clicking on "Toggle other content" is also slow.

You can observe it getting faster/slower depending on items count by changing ITEM_COUNT in code

Of course 5000 is not what real world app would have, but it emphasizes how long multiple renders can take.
issue/bug-unconfirmed
opened by Karolis92 0

Releases([email protected])

[email protected](Dec 1, 2022)
Minor Changes

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

Source code(tar.gz)
Source code(zip)
[email protected](Nov 14, 2022)
Patch Changes

cda16826 #5482 Thanks @nderkim! - Fix unstable theme rerendering menu

Source code(tar.gz)
Source code(zip)
[email protected](Nov 2, 2022)
Minor Changes

c37e86d8 #4882 Thanks @Rall3n! - Add required prop

Source code(tar.gz)
Source code(zip)
[email protected](Nov 1, 2022)
Patch Changes

851ed2b8 #5430 Thanks @Rall3n! - Fix focused option if defaultMenuIsOpen is set

Source code(tar.gz)
Source code(zip)
[email protected](Oct 31, 2022)
Patch Changes

1ad6de4e #5084 Thanks @kosciolek! - When focusing a dropdown option, the numbers included in the aria live region take filtering into consideration.

Source code(tar.gz)
Source code(zip)
[email protected](Oct 26, 2022)
Patch Changes

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

Source code(tar.gz)
Source code(zip)
[email protected](Oct 25, 2022)
Patch Changes

92398939 #5409 Thanks @lukebennett88! - Move files around to as to be compatible with version 2 of @preconstruct/cli

Source code(tar.gz)
Source code(zip)
[email protected](Oct 24, 2022)
Patch Changes

0dd38029 #5246 Thanks @Rall3n! - Fix re-focus of component in Firefox if being disabled while focused

Source code(tar.gz)
Source code(zip)
[email protected](Oct 20, 2022)
Patch Changes

ebb0a17a #5404 Thanks @Methuselah96! - Use ResizeObserver to auto-update menu position if available

Source code(tar.gz)
Source code(zip)
[email protected](Oct 20, 2022)
Patch Changes

07656aaa #5399 Thanks @dependabot! - Update memoize-one

Source code(tar.gz)
Source code(zip)
[email protected](Oct 18, 2022)
Patch Changes

00238f1a #5376 Thanks @lukebennett88! - Fix bug with animated multi-value select width being too wide

Source code(tar.gz)
Source code(zip)
[email protected](Oct 16, 2022)
Patch Changes

0f6ef093 #5381 Thanks @Methuselah96! - Disable use of ResizeObserver for menu position auto-updating to avoid potential breaking changes.

Source code(tar.gz)
Source code(zip)
[email protected](Oct 12, 2022)
Minor Changes

598f9ee0 #5256 Thanks @Methuselah96! - Auto-update menu position when using menu portalling

Source code(tar.gz)
Source code(zip)
[email protected](Jun 30, 2022)
Minor Changes

5d49f70a #5249 Thanks @Methuselah96! - Export formatOptionLabel types (i.e., FormatOptionLabelMeta and FormatOptionLabelContext).

Source code(tar.gz)
Source code(zip)
[email protected](May 8, 2022)
Patch Changes

1f140e42 #5177 Thanks @Methuselah96! - Fix view height used for menu positioning to be the scroll parent instead of the window

Source code(tar.gz)
Source code(zip)
[email protected](Apr 27, 2022)
Patch Changes

03bf7351 #5164 Thanks @Methuselah96! - Bump @emotion/react to ^11.8.1 to avoid useInsertionEffect bug

Source code(tar.gz)
Source code(zip)
[email protected](Apr 10, 2022)
Minor Changes

c7d8d4b3 #5133 Thanks @nil4! - Update peerDependencies to include React 18

Patch Changes

0aaa9575 #5134 Thanks @rkulinski! - Use defaultPrevented to skip duplicate event handler for clicking select.

87e14431 #5131 Thanks @pcorpet! - Avoid referencing an ID that is not in the DOM

7184d538 #5082 Thanks @Methuselah96! - Fix type inference for Async's loadOptions prop

bd4ee8ae #5057 Thanks @Rall3n! - Prevent transition props from being forwarded to <input> element in DummyInput component

Source code(tar.gz)
Source code(zip)
[email protected](Jan 13, 2022)
Patch Changes

940a50b1 #4928 Thanks @Methuselah96! - Fix usage with esModuleInterop disabled

54f9538e #4941 Thanks @prichey! - Use React's AriaAttributes type directly rather than recreating

e97d45c0 #4908 Thanks @vjee! - Make 3rd argument of CommonProps['setValue'] optional.

Source code(tar.gz)
Source code(zip)
[email protected](Nov 5, 2021)
Patch Changes

f172d7f9 #4886 Thanks @Akridian! - Hooks for creation of custom Selects are now exported from main entry

Source code(tar.gz)
Source code(zip)
[email protected](Nov 2, 2021)
Minor Changes

6c7a3d1e #4785 Thanks @Rall3n! - Add prevInputValue to action meta

b522ac65 #4860 Thanks @ebonow! - Fix animated MultiValue transitions when being removed and change method used to generate unqiue keys for Option components. Closes #4844 , closes #4602

Patch Changes

417e7217 #4842 Thanks @Methuselah96! - Remove src directory from published package

480ea85b #4846 Thanks @Methuselah96! - Add missing index to MultiValue props type

b8e34472 #4854 Thanks @mikunpham! - Make input container css re-compute whenever input value changes due to a bug from @emotion/react in development env.

Source code(tar.gz)
Source code(zip)
[email protected](Oct 5, 2021)
Minor Changes

8b38d49b #4807 Thanks @hcharley! - Export AsyncCreatableProps from creatable entrypoint

46eeda1a #4801 Thanks @Methuselah96! - Export more types from main entry point

Patch Changes

fdd01e66 #4833 Thanks @ebonow! - Value container display property should be grid when isMulti and has no value so the Placeholder component is positioned correctly with the Input

0937604f #4823 Thanks @mikunpham! - Fix the issue where input contents are moved to the left due to multiple space characters.

ec80b577 #4803 Thanks @Methuselah96! - Import CSSObject from @emotion/react instead of @emotion/serialize

Source code(tar.gz)
Source code(zip)
[email protected](Sep 23, 2021)
Upgrade Guide

Summary

Convert to TypeScript (#4489) - TypeScript types now come packaged with react-select so you no longer need to have @types/react-select installed; we no longer include Flow types

Drop IE11 support (#4625, #4720, #4634) - this allows us to make changes to our CSS that we've wanted to make for a long time as well as remove unnecessary JS solutions (those changes are noted below)

Use forwardRef for all wrapped components (#4489) - this means that if you were accessing anything on the Select instance using a ref, the ref will now reference the internal Select directly (see below for how to upgrade)

Replace HOCs with hooks (#4489) - if you were using our HOCs to create custom Selects (i.e., makeCreatableSelect, mangeState, makeAsyncSelect) these have now been replaced by hooks (i.e., useCreatable, useStateManager, useAsync)

Remove dependency on AutosizeInput (#4625) - our new solution uses CSS grid which IE11 does not fully support; also .prefix__input now targets the input and NOT the container

Improve screen reader experience (#4676) - this isn't a breaking change in the API but it does change the screen reader announcements

Use CSS grid for single value layout (#4720) - this also isn't a breaking change in the API but is it a change in the styles since it switches to using CSS grid (not fully supported by IE11) for single-value Selects

Remove readonly attribute on our DummyInput (#4634) - this results in better accessibility but uses caret-color which is not available on IE11

Details

Convert to TypeScript

We've rewritten react-select in TypeScript which means you can remove any dependencies on @types/react-select. If you were using the Flow types than look into contributing types for v5 to flow-typed.

Here are the most notable changes when replacing @types/react-select with our packaged types:

| @types/react-select | react-select | Notes | |--|--|--| | OptinTypeBase | no replacement | Options can be any type (if using getOptionValue and getOptionLabel) so there's no longer a base type for options | OptionsType | Options | | | GroupTypeBase | GroupBase | | | GroupedOptionsType | no replacement | This is equivalent to ReadonlyArray<Group> | | ValueType | OnChangeValue | | | InputActionTypes | InputAction | | | NamedProps | Props | | | Select (the ref type) | SelectInstance | See "Use forwardRef for all wrapped components" for more details | | AsyncSelect (the ref type) | SelectInstance | See "Use forwardRef for all wrapped components" for more details | | CreatableSelect (the ref type) | SelectInstance | See "Use forwardRef for all wrapped components" for more details | | AsyncCreatableSelect (the ref type) | SelectInstance | See "Use forwardRef for all wrapped components" for more details |

If you were previously importing a type from the src directory when using @types/react-select:

import { ... } from 'react-select/src/...';

These should now be imported from the dist/declarations/src directory:

import { ... } from 'react-select/dist/declarations/src/...';

We export any types from the main entry point that we think might be useful to the user. If you are using a type that is not exported from the main entry point please open a PR or issue so that we can add it.

If you are using custom props for the Select component you can use module augmentation to add them to the Select prop types:

declare module 'react-select/dist/declarations/src/Select' { export interface Props< Option, IsMulti extends boolean, Group extends GroupBase<Option> > { myCustomProp: string; } }

Drop IE11 support

This allows us to use modern CSS in order to improve the quality of react-select and remove excessive JavaScript code to work around not having the ability to use modern CSS. If you need IE11 support either:

Stay on v4.

Attempt to use our Styles API and/or Components API to override styles and/or components that don't support IE11. The only change that might be hard to override is "Remove readonly attribute on our DummyInput" since you can't override the DummyInput component with the Styles or Components API.

If there are simple changes that make react-select compatible with IE11, open a PR. We are unlikely to provide official support for IE11 since supporting IE11 makes maintaining react-select a lot more difficult and holds us back from changes we want to make, but we also are glad to accept simple changes if they make your life easier.

Use forwardRef for all wrapped components

NOTE: Accessing any of the internals of the Select component using refs is not part of our public API. The internals of the Select component can change at any time (including in minor and patch releases). The only methods on the Select component that are part of the public API are the focus() and blur() methods.

react-select exports five components: BaseSelect, CreatableSelect, Select (the default export), AsyncSelect, AsyncCreatableSelect. The last four components are wrappers around the BaseSelect. Previously the ref for each of these components was pointing to itself, but now we use forwardRef which means that the refs for all five components now point to BaseSelect.

The focus() and blur() methods are untouched by this change. However if you were accessing the internals of the BaseSelect component, you will need to update how you were accessing the BaseSelect. Here is how to update access to the BaseSelect component:

| Component | v4 | v5 | |--|--|--| | BaseSelect | ref | ref | | CreatableSelect | ref.select.select | ref | | Select | ref.select | ref | | AsyncSelect | ref.select.select | ref | | AsyncCreatableSelect | ref.select.select.select | ref |

Replace HOCs with hooks

The primary reason for this change is that hooks combined with generic components are easier to type in TypeScript than HOCs combined with generic components. These HOCs/hooks are considered advanced usage.

If you were using the HOCs, it shouldn't be too hard to replace them with its corresponding hook (i.e., useStateManager, useCreatable, or useAsync). As an example, here is how the state managed Select (the default export) used to be constructed with the mangeState HOC:

const Select = manageState(SelectBase);

With hooks it is now constructed like this:

const Select = (props) => { const baseSelectProps = useStateManager(props); return <SelectBase {...baseSelectProps} />; }

Consult the source code for how the other components are constructed.

Remove dependency on AutosizeInput

This is an exciting change because we get to drop our dependency on react-input-autosize. We now use a pure CSS solution to auto-size the input, however this means that we have to drop support for IE11 since IE11 does not fully support CSS grid. As part of this refactor the .prefix__input CSS class now targets the input itself and NOT the container. See #4625 for more details.

Improve screen reader experience

The following improvements have been made for screen reader users:

NVDA now announces the context text when initially focused

Selected option(s) (single and multi) are now announced when initially focused

VoiceOver now announces the context text when re-focusing

The clear action is now announced

Placeholder text is now announced

Mobile VoiceOver is now able to remove selected multi options

Also we've added the role of combobox and the required ARIA attributes to the Input and DummyInput components to allow JAWS support and a better screen reader experience overall. See #4695 for more details.

Use CSS grid for single value layout

Previously the absolution positioning of both the value and the placeholder pulled them out of the flow, and thus the component itself collapsed down when used as a flex child. To solve this we are now using CSS grid for the single value layout.

Remove readonly attribute on our DummyInput

Previously we added the readonly attribute to the DummyInput (when isSearchable is set to false) in order to hide the flashing cursor and prevent devices from showing a virtual keyboard. However the readonly attribute causes the DummyInput to be removed from the tab order in iOS Safari. In order to solve this we're replacing the readonly attribute with setting the caret-color CSS prop (which IE11 does not support) to transparent and setting the inputMode attribute on the <input> to none.

Changelog

Major Changes

ef87c3ac #4683 Thanks @Methuselah96! - React-Select has been converted from Flow to TypeScript.

Other changes for v5 include usage of forwardRef, new hooks for stateManager, async and creatable components, and more reliable filtering implementaion with new options in the creatable variant.

Patch Changes

10225290 #4720 - Updated the layout for the singleValue input/placeholder/container so that it works better when used in flex layouts.

53f1972b #4731 Thanks @JedWatson! - MultiValue key now includes a hyphen between the value and the index to prevent edge cases where you could get a duplicate key error

b41f4ceb #4704 Thanks @Rall3n! - Fix findDOMNode deprecation by adding refs to transition components

4b028829 #4634 - The readonly attribute has been removed from the DummyInput to improve accessibility

7fcec537 #4697 - Add the role of combobox and the required ARIA attributes to the Input and DummyInput components to allow JAWS support and a better screen reader experience overall.

ca2c0e5b #4756 Thanks @fdcds! - Add option field to type of CreateOptionActionMeta

9e82aadc #4676 - The following improvements have been made for screen reader users:

NVDA now announces the context text when initially focused

Selected option/s (single and multi) are now announced when initially focused

VoiceOver now announces the context text when re-focusing

The clear action is now announced

Placeholder text is now announced

Mobile VoiceOver is now able to remove selected multi options

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

23cea0b5 #4782 Thanks @Methuselah96! - Fix type of loadingMessage prop to allow it to return any ReactNode

Source code(tar.gz)
Source code(zip)
[email protected](Sep 3, 2021)
Patch Changes

10225290 #4720 - Updated the layout for the singleValue input/placeholder/container so that it works better when used in flex layouts.

53f1972b #4731 Thanks @JedWatson! - MultiValue key now includes a hyphen between the value and the index to prevent edge cases where you could get a duplicate key error

b41f4ceb #4704 Thanks @Rall3n! - Fix findDOMNode deprecation by adding refs to transition components

7fcec537 #4697 - Add the role of combobox and the required ARIA attributes to the Input and DummyInput components to allow JAWS support and a better screen reader experience overall.

9e82aadc #4676 - The following improvements have been made for screen reader users:

NVDA now announces the context text when initially focused

Selected option/s (single and multi) are now announced when initially focused

VoiceOver now announces the context text when re-focusing

The clear action is now announced

Placeholder text is now announced

Mobile VoiceOver is now able to remove selected multi options

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

Source code(tar.gz)
Source code(zip)
[email protected](Jul 9, 2021)
Major Changes

ef87c3ac #4489 Thanks @Methuselah96! - React-Select has been converted from Flow to TypeScript.

Other changes for v5 include usage of forwardRef, new hooks for stateManager, async and creatable components, and more reliable filtering implementaion with new options in the creatable variant.

#4625 Thanks @ebonow! - Remove dependency on AutoSizeInput

BREAKING CHANGES:

IE11 no longer works as it does not fully support CSS grid

Renaming the .prefix__input now targets the input and NOT the container. Unfortunate but overdue and perhaps opens the door to completely decoupling the input from needing a container if autosizing is not important.

Patch Changes

4b028829 #4634 - The readonly attribute has been removed from the DummyInput to improve accessibility

Source code(tar.gz)
Source code(zip)
[email protected](May 13, 2021)
Patch Changes

2c915d10 #4577 - Bump @emotion/cache to v11.4.0 which fixes an issue where different versions of Emotion running at the same time causes styles to disappear in production.

Source code(tar.gz)
Source code(zip)
[email protected](Mar 19, 2021)
Minor Changes

035294f4 #3360 Thanks @sunniejai!

focusedOption is now passed to the MenuList Component as a prop

Patch Changes

7a414a7c #3262 Thanks @torkelo!

The Menu bottom is no longer scrolled into view when menuShouldScrollIntoView=false

Documentation Updates

#4109 Thanks @manvydasu

Replaced componentWillReceiveProps with componentDidUpdate in docs

Source code(tar.gz)
Source code(zip)
[email protected](Mar 5, 2021)
Patch Changes

ca3c41bb #4478 Thanks @ebonow! - Check passive events polyfill for the existence of window for SSR

Source code(tar.gz)
Source code(zip)
[email protected](Mar 5, 2021)
Minor Changes

2ffed9c6 #4444 Thanks @Rall3n! - Use accessor props to get value and label in compareOption

2baf5a9d #4414 Thanks @ebonow! - Add ariaLiveMessages prop for internationalization and other customizations, add aria-live prop, and other accessibility fixes. Inspired heavily from the work done by @Kashkovsky, @radegran, @Malgalad, and @TheHollidayInn - thanks to them, @bozdoz for the thorough testing and recommendations, and for everyone who contributed constructive feedback towards a better accessibility experience.

7cdb8a6b #4391 Thanks @ebonow! - Pass and sanitize CommonProps passed to Group and Input components

Patch Changes

c955415c #4437 Thanks @ebonow! - Set event listeners to be non-passive to remove Chrome console warnings

3ca22b2f #3827 Thanks @mitchellhamilton! - Memoize stripDiacritics in createFilter for the input with memoize-one so that stripDiacritics is not called for the same string as many times as there are options every time the input changes

Inspired by https://blog.johnnyreilly.com/2019/04/react-select-with-less-typing-lag.html

dce3863f #4423 Thanks @Methuselah96! - Remove browser alias fields in order to fix SSR apps

ec7c0728 #4443 Thanks @ebonow! - Allow tabIndex prop Type to be number or string

Source code(tar.gz)
Source code(zip)
[email protected](Feb 7, 2021)
Minor Changes

b5f9b0c5 #4342 Thanks @Methuselah96! - Standardized innerProps and className props on customizable components

19b76342 #3911 Thanks @eugenet8k! - Add removedValues to onChange event meta when the action is clear (when the user clears the value in the Select)

Patch Changes

f600d13f #4422 Thanks @Methuselah96! - Fix finding focusable options for groups

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

10b5f5a5 #4404 Thanks @Methuselah96! - Remove unnecessary dependency on @emotion/css

Source code(tar.gz)
Source code(zip)
[email protected](Jan 22, 2021)
Patch Changes

44f285b0 #4399 Thanks @Methuselah96! - Fixed building focusable options from groups

Source code(tar.gz)
Source code(zip)