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 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 [].

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'

Is there anyways we could link this in release notes?

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

@carlreid

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

@gwyneplaine

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

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

@samjosephgates

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

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

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

@naniantero

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

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

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

@corysimmons

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

@bladey

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

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

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

Navigation Menu

Repository navigation

v3 upgrade guide #3585

Breaking Changes

What this means for you

Emotion 10

Multiple Entrypoints:

UMD Builds

Peer dependency on React 16.8

Normalized Values

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

v3 upgrade guide #3585

Description

Breaking Changes

What this means for you

Emotion 10

Multiple Entrypoints:

UMD Builds

Peer dependency on React 16.8

Normalized Values

Activity

carlreid commented on May 27, 2019

iraSenthil commented on Jun 24, 2019

Methuselah96 commented on Jun 26, 2019

nzayatz14 commented on Aug 28, 2019

samjosephgates commented on Aug 29, 2019

naniantero commented on Oct 1, 2019

cosminn777 commented on Oct 10, 2019

shurygindv commented on Nov 18, 2019

deybith commented on Apr 28, 2020

ianstormtaylor commented on Jun 7, 2020

corysimmons commented on Jun 22, 2020

bladey commented on Jun 23, 2020

corysimmons commented on Jun 23, 2020

ConradSollitt commented on Oct 19, 2020

ebonow commented on Dec 4, 2020

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions