Migrating to Spectrum 2

An automated upgrade assistant is available by running the following command in the project you want to upgrade:

npx @react-spectrum/codemods s1-to-s2

To only upgrade specific components, provide a --components argument with a comma-separated list of components to upgrade:

npx @react-spectrum/codemods s1-to-s2 --components=Button,TextField

The following arguments are also available:

• --path - Path to apply the upgrade changes to. Defaults to the current directory (.)
• --dry - Runs the upgrade assistant without making changes to components
• --ignore-pattern - Ignore files that match the provided glob expression. Defaults to '**/node_modules/**'

For cases that the upgrade assistant doesn't handle automatically or where you'd rather upgrade some components manually, use the guide below.

Note that Pending indicates that future changes will occur before the final release, and the current solution should be considered temporary.

Components

All components

• Update imports to use the @react-spectrum/s2 package instead of @adobe/react-spectrum or individual packages like @react-spectrum/button
• Update style props to use the style macro instead. See the 'Style props' section below

Accordion

• Update Item to be Disclosure. Disclosure should now consist of two children: DisclosureTitle and DisclosurePanel. Note that you can now add interactive elements inside the header and adjacent to the title by using the DisclosureHeader component with the DisclosureTitle and interactive elements inside.
• Update Item's title prop to be a child of DisclosureTitle
• Update children of Item to be children of DisclosurePanel
• Update key to be id (and keep key if rendered inside array.map)
• Remove disabledKeys and add isDisabled to individual Disclosure components
• Add allowsMultipleExpanded to allow multiple Disclosure components to be expanded at once (previously default behavior)

ActionBar

• Remove ActionBarContainer and move ActionBar to renderActionBar prop of TableView or CardView
• Update Item to ActionButton
• Update root level onAction to be called via onPress on each ActionButton
• Apply isDisabled directly on each ActionButton or ToggleButton instead of root level disabledKeys
• Update key to be id (and keep key if rendered inside array.map)
• Convert dynamic collections render function to items.map
• Pending Comment out buttonLabelBehavior (it has not been implemented yet)

ActionButton

No updates needed.

ActionMenu

• Pending Comment out closeOnSelect (it has not been implemented yet)
• Pending Comment out trigger (it has not been implemented yet)
• Update Item to be a MenuItem

ActionGroup

• Use ActionButtonGroup if you are migrating from an ActionGroup that didn't allow for selection. ActionButtonGroup takes ActionButtons as children.
• Use ToggleButtonGroup if you are migrating from an ActionGroup that used single or multiple selection. ToggleButtonGroup takes ToggleButtons as children.
• Pending Comment out overflowMode (it has not been implemented yet)
• Pending Comment out buttonLabelBehavior (it has not been implemented yet)
• Pending Comment out summaryIcon (it has not been implemented yet)
• Update root level onAction to called via onPress on each ActionButton
• Apply isDisabled directly on each ActionButton or ToggleButton instead of root level disabledKeys
• Update key to be id (and keep key if rendered inside array.map)
• Convert dynamic collections render function to items.map

AlertDialog

No updates needed.

Avatar

• Pending Comment out isDisabled (it has not been implemented yet)
• Update size to be a pixel value if it currently matches 'avatar-size-*'

Badge

• Change variant="info" to variant="informative"

Breadcrumbs

• Pending Comment out showRoot (it has not been implemented yet)
• Pending Comment out isMultiline (it has not been implemented yet)
• Pending Comment out autoFocusCurrent (it has not been implemented yet)
• Remove size="S" (Small is no longer a supported size in Spectrum 2)
• Update Item to be a Breadcrumb

Button

• Change variant="cta" to variant="accent"
• Change variant="overBackground" to variant="primary" staticColor="white"
• Change style to fillStyle
• Remove isQuiet (it is no longer supported in Spectrum 2)
• If href is present, the Button should be converted to a LinkButton
• Remove elementType (it is no longer supported in Spectrum 2)

ButtonGroup

No updates needed.

Calendar

No updates needed.

Checkbox

No updates needed.

CheckboxGroup

• Remove showErrorIcon (it has been removed due to accessibility issues)

ColorArea

• Remove size and instead provide a size via the style macro (i.e. styles={style({size: 20})})

ColorField

• Remove isQuiet (it is no longer supported in Spectrum 2)
• Change validationState="invalid" to isInvalid
• Remove validationState="valid" (it is no longer supported in Spectrum 2)

ColorSlider

• Remove showValueLabel (it has been removed due to accessibility issues)

ColorSwatch

No updates needed.

ColorWheel

• Remove size and instead provide a size via the style macro (i.e. styles={style({size: 20})})

ComboBox

• Change menuWidth value from a DimensionValue to a pixel value
• Remove isQuiet (it is no longer supported in Spectrum 2)
• Change validationState="invalid" to isInvalid
• Remove validationState="valid" (it is no longer supported in Spectrum 2)
• Update Item to be a ComboBoxItem

DateField

• Remove isQuiet (it is no longer supported in Spectrum 2)
• Change validationState="invalid" to isInvalid
• Remove validationState="valid" (it is no longer supported in Spectrum 2)

DatePicker

• Remove isQuiet (it is no longer supported in Spectrum 2)
• Change validationState="invalid" to isInvalid
• Remove validationState="valid" (it is no longer supported in Spectrum 2)

DateRangePicker

• Remove isQuiet (it is no longer supported in Spectrum 2)
• Change validationState="invalid" to isInvalid
• Remove validationState="valid" (it is no longer supported in Spectrum 2)

Dialog

• Update children to move render props from being the second child of DialogTrigger to being a child of Dialog
• Remove onDismiss and use onOpenChange on the DialogTrigger, or onDismiss on the DialogContainer instead
• Dialog is now meant specifically for rendering modal dialogs only and follows the same preset layout as before
• If you are trying to create a dialog with a custom layout use CustomDialog
• If you are trying to create a fullscreen dialog use FullscreenDialog
• If you are trying to create a popover dialog use Popover
• Supports isKeyboardDismissDisabled in place of DialogTrigger
• Supports isDismissible in place of DialogTrigger. Note the fixed spelling from previous isDismissible prop.
• Supports role: "dialog" | "alertdialog"

DialogContainer

• Remove type, this is dependent on the dialog level child that you use (e.g. Dialog, FullscreenDialog, Popover)
• Remove isDismissable, prop now exists on the dialog level component as isDismissible
• Remove isKeyboardDismissDisabled, prop now exists on the dialog level component

DialogTrigger

• Pending Comment out type="tray" (Tray has not been implemented yet)
• Pending Comment out mobileType (Tray and other types have not been implemented yet for Popover)
• Remove targetRef (it is no longer supported in Spectrum 2)
• Update children to remove render props usage, and note that the close function was moved from DialogTrigger to Dialog
• Remove containerPadding, prop now exists on the Popover component
• Remove crossOffset, prop now exists on the Popover component
• Remove hideArrow, prop now exists on the Popover component
• Remove isDismissable, prop now exists on the dialog level component as isDismissible
• Remove isKeyboardDismissDisabled, prop now exists on the dialog level component
• Remove offset, prop now exists on the Popover component
• Remove placement, prop now exists on the Popover component
• Remove shouldFlip, prop now exists on the Popover component
• Remove type, this is dependent on the dialog level child that you use (e.g. Dialog, FullscreenDialog, Popover)

Divider

• Remove Divider component if within a Dialog (Updated design for Dialog in Spectrum 2)

Flex

• Update Flex to be a div and apply flex styles using the style macro (i.e. <div className={style({display: 'flex'})} />)

Form

• Remove isQuiet (it is no longer supported in Spectrum 2)
• Remove isReadOnly (it is no longer supported in Spectrum 2)
• Remove validationState (it is no longer supported in Spectrum 2)
• Remove validationBehavior (it is no longer supported in Spectrum 2)

Grid

• Update Grid to be a div and apply grid styles using the style macro (i.e. <div className={style({display: 'grid'})} />)

IllustratedMessage

• Update illustrations to be from @react-spectrum/s2/illustrations. See Illustrations

InlineAlert

• Change variant="info" to variant="informative"

Item

• If within Menu: Update Item to be a MenuItem
• If within ActionMenu: Update Item to be a MenuItem
• If within TagGroup: Update Item to be a Tag
• If within Breadcrumbs: Update Item to be a Breadcrumb
• If within Picker: Update Item to be a PickerItem
• If within ComboBox: Update Item to be a ComboBoxItem
• If within ListBox: Update Item to be a ListBoxItem
• If within TabList: Update Item to be a Tab
• If within TabPanels: Update Item to be a TabPanel and remove surrounding TabPanels
• Update key to be id (and keep key if rendered inside array.map)

Link

• Change variant="overBackground" to staticColor="white"
• If a was used inside Link (legacy API), remove the a and apply props (i.e href) directly to Link

ListBox

• Update Item to be a ListBoxItem

Menu

• Update Item to be a MenuItem

MenuTrigger

• Pending Comment out closeOnSelect (it has not been implemented yet)

NumberField

• Remove isQuiet (it is no longer supported in Spectrum 2)
• Change validationState="invalid" to isInvalid
• Remove validationState="valid" (it is no longer supported in Spectrum 2)

Picker

• Change menuWidth value from a DimensionValue to a pixel value
• Remove isQuiet (it is no longer supported in Spectrum 2)
• Change validationState="invalid" to isInvalid
• Remove validationState="valid" (it is no longer supported in Spectrum 2)
• Update Item to be a PickerItem
• Change isLoading to loadingState and provide the appropriate loading state.
• Update defaultSelectedKey and selectedKey to be defaultValue and value respectively. See the Picker documentation for more details.

ProgressBar

• Change variant="overBackground" to staticColor="white"
• Pending Comment out labelPosition (it has not been implemented yet)
• Pending Comment out showValueLabel (it has not been implemented yet)

ProgressCircle

• Change variant="overBackground" to staticColor="white"

Radio

No updates needed.

RadioGroup

• Change validationState="invalid" to isInvalid
• Remove validationState="valid" (it is no longer supported in Spectrum 2)
• Remove showErrorIcon (it has been removed due to accessibility issues)

RangeCalendar

No updates needed.

RangeSlider

• Remove showValueLabel (it has been removed due to accessibility issues)
• Pending Comment out getValueLabel (it has not been implemented yet)
• Pending Comment out orientation (it has not been implemented yet)

SearchField

• Pending Comment out icon (it has not been implemented yet)
• Remove isQuiet (it is no longer supported in Spectrum 2)
• Change validationState="invalid" to isInvalid
• Remove validationState="valid" (it is no longer supported in Spectrum 2)

Section

• If within Menu: Update Section to be a MenuSection
• If within Picker: Update Section to be a PickerSection

Slider

• Remove isFilled (Slider is always filled in Spectrum 2)
• Remove trackGradient (Not supported in S2 design)
• Remove showValueLabel (it has been removed due to accessibility issues)
• Pending Comment out getValueLabel (it has not been implemented yet)
• Pending Comment out orientation (it has not been implemented yet)

StatusLight

• Remove isDisabled (it is no longer supported in Spectrum 2)
• Change variant="info" to variant="informative"

SubmenuTrigger

No updates needed.

Switch

No updates needed.

TableView

• For Column and Row: Update key to be id (and keep key if rendered inside array.map)
• For dynamic tables, pass a columns prop into Row
• For Row: Update dynamic render function to pass in column instead of columnKey
• Move loadingState and onLoadMore from TableBody to TableView
• Pending Comment out UNSTABLE_allowsExpandableRows (it has not been implemented yet)
• Pending Comment out UNSTABLE_onExpandedChange (it has not been implemented yet)
• Pending Comment out UNSTABLE_expandedKeys (it has not been implemented yet)
• Pending Comment out UNSTABLE_defaultExpandedKeys (it has not been implemented yet)

Tabs

• Inside TabList: Update Item to be Tab
• Update items on Tabs to be on TabList
• Inside TabPanels: Update Item to be a TabPanel and remove the surrounding TabPanels
• Remove isEmphasized (it is no longer supported in Spectrum 2)
• Remove isQuiet (it is no longer supported in Spectrum 2)

TagGroup

• Rename actionLabel to groupActionLabel
• Rename onAction to onGroupAction
• Change validationState="invalid" to isInvalid
• Update Item to be Tag

TextArea

• Pending Comment out icon (it has not been implemented yet)
• Remove isQuiet (it is no longer supported in Spectrum 2)
• Change validationState="invalid" to isInvalid
• Remove validationState="valid" (it is no longer supported in Spectrum 2)

TextField

• Pending Comment out icon (it has not been implemented yet)
• Remove isQuiet (it is no longer supported in Spectrum 2)
• Change validationState="invalid" to isInvalid
• Remove validationState="valid" (it is no longer supported in Spectrum 2)

TimeField

• Remove isQuiet (it is no longer supported in Spectrum 2)
• Change validationState="invalid" to isInvalid
• Remove validationState="valid" (it is no longer supported in Spectrum 2)

ToggleButton

No updates needed.

Tooltip

• Remove variant (it is no longer supported in Spectrum 2)
• Remove placement and add to the parent TooltipTrigger instead
• Remove showIcon (it is no longer supported in Spectrum 2)
• Remove isOpen and add to the parent TooltipTrigger instead

TooltipTrigger

• Update placement prop to have one value (i.e. Update placement="bottom left" to be placement="bottom")

TreeView

If migrating from TreeView version 3.0.0-beta.3 or before, please do the following. Otherwise, no updates needed.

• Update content within TreeViewItem to be wrapped in TreeViewContentItem

View

• Update View to be a div and apply styles using the style macro

Well

Update Well to be a div and apply styles using the style macro:

<div className={style({
  display: 'block',
  textAlign: 'start',
  padding: 16,
  minWidth: 160,
  marginTop: 4,
  borderWidth: 1,
  borderRadius: 'sm',
  borderStyle: 'solid',
  borderColor: 'transparent-black-75',
  font: 'body-sm'
})} />

Style props

React Spectrum v3 supported a limited set of style props for layout and positioning using Spectrum-defined values. Usage of these should be updated to instead use the style macro.

Border width

Affected style props: borderWidth, borderStartWidth, borderEndWidth, borderTopWidth, borderBottomWidth, borderXWidth, borderYWidth.

Border widths should be updated to use pixel values. Use the following mappings:

Border radius

Affected style props: borderRadius, borderTopStartRadius, borderTopEndRadius, borderBottomStartRadius, borderBottomEndRadius.

Border radius values should be updated to use pixel values. Use the following mappings:

Dimension values

Affected style props: width, minWidth, maxWidth, height, minHeight, maxHeight, margin, marginStart, marginEnd, marginTop, marginBottom, marginX, marginY, top, bottom, left, right, start, end, flexBasis, gap, columnGap, rowGap, padding, paddingX, paddingY, paddingStart, paddingEnd, paddingTop, paddingBottom.

Dimension values should be converted to pixel values. Use the following mappings:

Break points

Break points previously used in style props can be used in the style macro with updated keys. Use the following mappings: