[email protected]

Upgrade Guide

Summary

• Standardize value passed to onChange (#4339) - the onChange handler is now always passed an array of options if isMulti is set to true
• Emotion 11 (#4283) - should only affect you if you're using the NonceProvider component
• Remove usage of UNSAFE React methods (#4313) - shouldn't affect you except now you won't see those warning messages in the console anymore

Details

Standardize value passed to onChange

This change makes it so that the first parameter passed to the onChange callback will now always be an array of options if isMulti is set to true and will always be a single option or null if isMulti is set to false. Previously the first parameter of onChange could be an array or null when isMulti was set to true.

That means if you were previously using nullish coalescing in order to handle null for isMulti:

<Select
  isMulti
  onChange={(newValues) =>  setValues(newValues ?? [])}
/>

You can now remove the nullish coalescing because onChange will always be an array when isMulti is set to true:

<Select
  isMulti
  onChange={(newValues) =>  setValues(newValues)}
/>

Emotion 11

The NonceProvider component now requires a cacheKey prop that corresponds to the newly required key prop for the Emotion cache. This won't affect you if you aren't using NonceProvider. See #4283 for more details.

Remove usage of UNSAFE React methods

This isn't necessarily a breaking change, but it required a large refactor in order to accomplish so we released this in a major upgrade in case it has some unintended consequences.

Changelog

Major Changes

• 02050675 #4339 Thanks @Methuselah96! - Standardized value passed to onChange

• 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.

• b2488bb5 #4313 Thanks @Methuselah96! - Removed usages of UNSAFE React methods

Patch Changes

• 2d5496d5 #4388 Thanks @Methuselah96! - Removed memoization of buildMenuOptions

[email protected]

Minor Changes

• c615e93d #4084 Thanks @JedWatson! - Changed the cx and getValue props that are passed to components into instance properties, which means they now pass a referential equality check on subsequent renders.

  This is helpful, for example, when you're optimising the performance of rendering custom Option components - see #3055

• 72f6036f #4306 Thanks @bladey! - Remove duplicate prop createOptionPosition

Patch Changes

• ee638d46 #4275 Thanks @Methuselah96! - Adds react ^17.0.0 to peer dependencies for React 17 support

• a0133f19 #4154 Thanks @brenshanny! - Creatable: Fixed removing MultiValues that have identical values. See issue #4137 for details.

• d1e660c6 #4213 Thanks @eythort! - Added a guard to the ScrollCaptor component to check that el exists before calling removeEventListener, fixes intermittent errors

• a1e1db25 #4373 Thanks @Methuselah96! - Fixed value passed to onChange when clearing value

• 2ad29d61 #4136 Thanks @Methuselah96! - Base aria-live message on tabSelectsValue prop

• ad890f27 #4326 Thanks @Methuselah96! - Updated react-input-autosize to v3.0.0

• b28d9922 #3990 Thanks @nikitaindik! - Fixed onCreateOption is not always called for Creatable

• 24ba8702 #4289 Thanks @slimklim! - Added innerProps prop to the built-in MenuList component to reduce the need for additional DOM nodes or forking internal code when passing additional props to the DOM element the MenuList component is rendering.

  See issue #4265 for an explanation.

[email protected]

Patch Changes

• c8d74bd5 #3979 Thanks @mitchellhamilton! - Fix repository field

• c8447f48 #4034 Thanks @sophiebits! - Improve performance of option filtering when ignoreAccents is enabled (the default)

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

• 32ad5c04 #3892 Thanks @flexdinesh! - Fix react-select ignoring HTML5 "form" attribute

• 6af14fbb #3897 Thanks @lorisdev! - Removes the call to onMenuOpen on every input change

  If you were relying on this undesired behavior it may be a breaking change.
  Please upgrade accordingly.

• 0eb1ef96 Thanks @JedWatson! - Fixes touch issues in IE11

• ad608c8f #3928 Thanks @dpordomingo! - Update MenuPlacer context usage in order to the new React Context API

[email protected]

Minor Changes

• 4cf6c43c #3690 Thanks @JedWatson! - Add isLoading prop support to the AsyncSelect component (see #3690)

Patch Changes

• 83b48de4 #3868 Thanks @Tirzono! - Fix for not focusing the selected value when the menu opens
• 563b046a #3794 Thanks @mitchellhamilton! - Convert class components that don't have to be class components to function components to reduce bundle size
• c7e9c697 #3682 Thanks @JedWatson! - Allow the input component to be a textarea element
• 3c7de0de #3090 Thanks @akiselev! - Add aria attributes to dummy input
• d2a820ef #3537 Thanks @jdelStrother! - Fix Flow issues. Refer to the linked PR for more details on the specific issues.
• fc52085b #3662 Thanks @eemeli! - Update react-transition-group to ^4.3.0
• edb18dd3 #3797 Thanks @mitchellhamilton! - Enable Babel loose mode to improve bundle size

[email protected]

Patch Changes

• a575a3c4 #3727 Thanks @tonytangau! - Adding an index prop to MultiValue components
• 916f0d2c #3644 Thanks @TrySound! - Remove usage of raf package and replace with window.requestAnimationFrame because React already depends on requestAnimationFrame
• cba15309 #3676 Thanks @wiesys! - Fix loadingMessage and noOptionsMessage properties in Styles flow type
• 32f9475e #3790 Thanks @JedWatson! - Remove unnecessary dependency on classnames package
• 1731175d #3733 Thanks @ddc67cd! - Pass name to onChange meta in Creatable to make it consistent with onChange in standard Select

v3.0.3

The core motivation behind 3.0.0 is to set us up to leverage new tools to make react-select better. As such we've made the following changes:

Breaking Changes

• Upgrade from Emotion 9 to Emotion 10
• UMD builds deprecated
• Multiple Entrypoints
• React 16.8 required as peer dependencies
• Normalized Values #3416

What this means for you

Emotion 10

Moving to the latest major version of emotion affords us zero-config SSR and enabling easier CSP support. Unfortunately this will be a breaking change for consumers who are currently leveraging emotion to build custom components for react-select. For example, you'd previously create an custom Option component with emotion like so:

import { css } from 'emotion'

const customOption = ({ cx, className, getStyles, _ }) => 
  <div 
     classNames={cx(
       css(getStyles('option', props)), 
       {
         'option': true,
         'option--is-disabled': isDisabled,
         'option--is-focused': isFocused,
         'option--is-selected': isSelected,
        },
        className
     )}
     {...}
  >

With react-select 3.0.0, and emotion 10 it would be the following:

/** @jsx jsx */
import { jsx } from '@emotion/core';

const customOption = ({ cx, className, getStyles, _ }) => 
  <div 
    css={getStyles('option', props)}
    classNames={cx(
     {
       'option': true,
       'option--is-disabled': isDisabled,
       'option--is-focused': isFocused,
       'option--is-selected': isSelected,
      },
      className
    )} 
    {...}
  >

Multiple Entrypoints:

v3.0.0 separates removes the following components from the main entry point, and instead exports them as separate entrypoints:

• Async (now exported from react-select/async)
• Creatable (now exported from react-select/creatable)
• Async Creatable (now exported from react-select/async-creatable)
• makeAnimated and default animated components (now exported from react-select/animated)

Where you’d previously import them as such

	import { Async } from 'react-select'  

Or as:

	import Async from 'react-select/lib/Async'

Now imports look like this:

	import AsyncSelect from 'react-select/async'

This should have no bundle-size impact on react-select consumers currently leveraging tree-shaking. However for consumers who aren’t leveraging tree-shaking, this should help alleviate some of the bundle-weight.

UMD Builds

UMD builds have been removed as of react-select v3.

Peer dependency on React 16.8

We've decided on requiring 16.8 as a peer dependency for react-select 3.0.0. This is motivated by our commitment to leveraging the improvements in recent versions of React such as hooks to make react-select even better.

Normalized Values

At the moment, if no value is specified by the consumer, it's instantiated as a null value, regardless of whether the select isMulti or not.

When isMulti is false this is fine. On selection of an option, the value becomes an object, and on clearing of said value, it returns to being null. (null --> {} --> null)

However when isMulti is true, this becomes more inconsistent. On selection of options, the value becomes an array of options, removing values extricates them from this array, removing the last selected value results in an empty array, instead of the initial base state of null.
(null --> [{}] --> [])

We rectify this in 3.0.0, on removal of all selected values in an isMulti Select, the value passed to onChange is null and not [].

• Remove base entrypoint to fix rollup dependency resolution issue in 3.0.3
• See #3585 for a detailed list of changes in 3.0.0

v2.4.2 / 2019-03-11

Bug fixes

• #3446 Fix bug with select input value not being selectable. Thanks @kangweichan
• #3445 Fix accessibility bug. Disabled options are now focusable and announced by screen-readers but not selectable. Thanks @sarahbethfederman

Updates

• Fixed typo in style docs. Thanks thiagodebastos.
• #3460 Added description for actionTypes to docs. Thanks @mikekellyio

v2.4.1 / 2019-02-18

Bug fixes

• #3432 Fix bug with select menu's not working on mobile.

v2.4.0 / 2019-02-15

Bug fixes

• #3427 remove focusOption() invocation on ENTER press if the menu is not open.
• #3402 fix menu scroll being reset on focus of a select with an open menu in ie11. See #3342 for details. Thanks timothypage
• #3420 fixed select menu being opened on click, when openMenuOnClick is false. Thanks caleb and rscotten
• #3419 fixed bug with ScrollCaptor operating on an undefined scrollTarget. Thanks iulian-radu-at
• #3411 fix bug where Enter key press on select with a closed menu wouldn't propagate up. Resolves #2217.
• #3407 remove unnecessary aria-roles from menu and options. This is now all handled by our aria-live implementation. Resolves #3355. Thanks sarahbethfederman.
• #3393, fix aria live announcement text for removing a selected option. Thanks msharkeyiii.
• #3350 Updated to 0.91 of flow. Updated types to pass stricter type checking, in later versions of flow. Thanks DragonWW

Updates

• #3370 Updated memoize-one dependency to 5.0.0. Thanks adam187
• #3366 Update build tooling, to leverage babel 7. Thanks DragonWW

v2.3.0 / 2019-01-18

Bug fixes

• #3315 add RAF call to Collapse component getRef() such that getBoundingClientRect() is invoked consistently.
• #3275 wrap String invocation around inputValue to avoid calling toLowerCase on invalid elements. thanks tavareshenrique
• #3357, fix loadOptions call in Async select to always pass in a string for the inputValue.
• #3346 Revert work done in CSP nonce PR #3260 to unblock react-select usage in an SSR setting. Users who need nonce support still, please pin your version of react-select at 2.2.0. Nonce support will be re-added in 3.0.0 along with an upgrade to emotion 10; which includes nonce support without having to provide a custom emotion instance.

Features

• #3115 menu-is-open modifier added to control class when the menu is open. @s20lee