v3 upgrade guide

The core motivation behind 3.0.0 is to set us up to leverage new tools to make react-select better. We’ve also made some 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 [].

[carlreid]

Would be awesome if you could update typings for this too. Currently don’t believe I can import like so: import AsyncSelect from 'react-select/async'

[iraSenthil]

Is there anyways we could link this in release notes?

I usually look at release notes to figure out breaking changes before upgrading.