v3 upgrade guide

[gwyneplaine]

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 3.x Normalise value removal #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.

[Methuselah96]

@carlreid I made a PR to update the types: DefinitelyTyped/DefinitelyTyped#36464.

[nzayatz14]

Hey @gwyneplaine @JedWatson, do you guys think you could also update https://github.com/JedWatson/react-input-autosize to be for react 16.8? There are a few issues with the newly deprecated functions (i.e. componentWillReceiveProps)

Issue here:

JedWatson/react-input-autosize#163

[samjosephgates]

Can you explain how CSP support has been added? I can't find any documentation on how to configure the nonce within the control.

[naniantero]

@samjosephgates You need to wrap your selects with NonceProvider, which you can import from react-select. Just provide your nonce to it as a prop. At least that's how I got it working. It's not documented anywhere, tho..

[cosminn777]

Why were the UMD builds deprecated and how can I run v3 in browser?

[shurygindv]

is there an approximate release date of a fix? We need this! React 16.12 has a lit bit incompatible changes in typings

In React.16.8 (react-select uses it)

    interface FocusEvent<T = Element> extends SyntheticEvent<T, NativeFocusEvent> {
        relatedTarget: EventTarget;
        target: EventTarget & T;
    }

but in the same time React 16.12

    interface FocusEvent<T = Element> extends SyntheticEvent<T, NativeFocusEvent> {
        relatedTarget: EventTarget | null;
        target: EventTarget & T;
    }

diff in relatedTarget: EventTarget | null;

in principle, I generally can't migrate on React 16.12 due different scheduler react versions

[deybith]

How to use nonce with the new version ? I can't see in anywhere.

@naniantero can you explain how do you do more in detail.

Thanks

[ianstormtaylor]

Why did the UMD build gets deprecated? How can you use react-select directly from a CDN like Unpkg now?

[corysimmons]

react-select now blows up console with deprecation warnings from react. :(

[bladey]

Hey @corysimmons, we're aiming to get this addressed soon - #4094

[corysimmons]

@bladey Awesome, thanks for the update and all your hard work!

[ConradSollitt]

Can UMD Version still be kept? Does keeping it cause any problems or prevent new features?

I think having a UMD is still useful. For example I created a demo of using the UMD version at the following site and would like the have the option in the future. If not I'll just plan on linking to the older version before UMD is deprecated.

https://awesome-web-react.js.org/examples/select-controls/react-select.htm

[ebonow]

Greetings everyone. I will be closing this issue. A couple points to close out with...

• This issue will remain pinned to make it easier to find until the documentation includes an upgrade guide to v3
• I have added this initial post to the v3.0.3 release notes making it hopefully easier to find for those searching through the version changes
• It is known that UMD support is a feature request for many and believe that it does belong on the roadmap. There are other existing issues that address this and will likely track this feature here: react-select.browser.*.js doesn't work from the browser via cdn #4120