The Select component has been upgraded!
The original version of the React Magma Select was built upon React Select by Jed Watson.
The components Select, AsyncSelect, CreatableSelect, and AsyncCreatableSelect have been moved to react-magma-legacy-selects and will no longer be maintained.
The new version includes both the Select (replacing the old Select and AsyncSelect) and Combobox (replacing CreateableSelect and AsyncCreatableSelect) components, built upon Downshift.
We recommend migrating to the new components as soon as possible. The major differences in the new version are outlined here.
Installing Downshift
downshift is a peerDependency of react-magma-dom. Install downshift using npm i --save downshift@5.4.7.
Remove React Select
react-select is no longer needed as a peerDependency if you are only using the new components. Remove react-select from your dependencies.
Options/Items
Both the LegacySelect and new Select component take an array of options. However the property name has changed from options in LegacySelect to items in the new Select component.
Each item in the items array can either be a string or an object with the shape {item: string; label: string;}, as shown in the Basic Usage examples.
In the new component, you may also pass in a custom shape for your items, by passing in an additional prop named itemToString,
which is a function that returns the string representation of your item which will be applied as the label. The same formats apply to the Combobox component.
Async
The Select and the Combobox no longer have separate components for asynchronous loading of options.
To create the equivalent of LegacyAsyncCreatableSelect you can pass in the new options to an Async Combobox with the isLoading prop to indicate that the new options are loading.
To create the equivalent of the LegacyAsyncSelect, you would use the Async Combobox component with the prop disableCreateItem in addition to isLoading.
Events
The onChange prop from the LegacySelect has been replaced with the onSelectedItemChange prop in the upgraded version.
The onMenuOpen and onMenuClose props from the LegacySelect have been replaced with onIsOpenChange.
Additionally, two new event props, onHighlightedIndexChange and onStateChange are also available.
See the docs for information on Specific State Changes and Generic State Change.
Accessibility
New to the upgraded Select and Combobox components, are some new props to allow for customization of the screen-reader accessible messages.
The getA11yStatusMessage prop is used to indicate when one the following props are changed: items, highlightedIndex, inputValue or isOpen.
The getA11ySelectionMessage prop is used to indicate when an item has been selected.
Custom Styles
New to the upgraded Select and Combobox components, is the ability to add custom styles by passing CSS properties.