# Migrating to Spectrum 2

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

<InstallCommand
  isCommand
  pkg="@react-spectrum/codemods"
  flags="s1-to-s2"
/>

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

<InstallCommand
  isCommand
  pkg="@react-spectrum/codemods"
  flags="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 <PendingBadge/> 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](https://react-spectrum.adobe.com/react-spectrum/styling.html#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`
* <PendingBadge/> Comment out `buttonLabelBehavior` (it has not been implemented yet)

### ActionButton

No updates needed.

### ActionMenu

* <PendingBadge/> Comment out `closeOnSelect` (it has not been implemented yet)
* <PendingBadge/> 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.
* <PendingBadge/> Comment out `overflowMode` (it has not been implemented yet)
* <PendingBadge/> Comment out `buttonLabelBehavior` (it has not been implemented yet)
* <PendingBadge/> 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

* <PendingBadge/> 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

* <PendingBadge/> Comment out `showRoot` (it has not been implemented yet)
* <PendingBadge/> Comment out `isMultiline` (it has not been implemented yet)
* <PendingBadge/> 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)
* Remove `placeholder` (it has been removed due to accessibility issues)
* 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)
* Remove `placeholder` (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

* <PendingBadge/> Comment out `type="tray"` (`Tray` has not been implemented yet)
* <PendingBadge/> 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

* <PendingBadge/> 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.

### ProgressBar

* Change `variant="overBackground"` to `staticColor="white"`
* <PendingBadge/> Comment out `labelPosition` (it has not been implemented yet)
* <PendingBadge/> 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)
* <PendingBadge/> Comment out `getValueLabel` (it has not been implemented yet)
* <PendingBadge/> Comment out `orientation` (it has not been implemented yet)

### SearchField

* Remove `placeholder` (it has been removed due to accessibility issues)
* <PendingBadge/> 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)
* <PendingBadge/> Comment out `getValueLabel` (it has not been implemented yet)
* <PendingBadge/> 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`
* <PendingBadge/> Comment out `UNSTABLE_allowsExpandableRows` (it has not been implemented yet)
* <PendingBadge/> Comment out `UNSTABLE_onExpandedChange` (it has not been implemented yet)
* <PendingBadge/> Comment out `UNSTABLE_expandedKeys` (it has not been implemented yet)
* <PendingBadge/> 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

* <PendingBadge/> Comment out `icon` (it has not been implemented yet)
* Remove `isQuiet` (it is no longer supported in Spectrum 2)
* Remove `placeholder`  (it has been removed due to accessibility issues)
* Change `validationState="invalid"` to `isInvalid`
* Remove `validationState="valid"` (it is no longer supported in Spectrum 2)

### TextField

* <PendingBadge/> Comment out `icon` (it has not been implemented yet)
* Remove `isQuiet` (it is no longer supported in Spectrum 2)
* Remove `placeholder`  (it has been removed due to accessibility issues)
* 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:

```tsx
<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](https://react-spectrum.adobe.com/react-spectrum/styling.html#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:

<StaticTable
  headers={[
    'Spectrum 1',
    'Spectrum 2'
  ]}
  rows={[
    ["'none'", 0],
    ["'thin'", 1],
    ["'thick'", 2],
    ["'thicker'", 4],
    ["'thickest'", "'[8px]'"]
  ]}
  codeColumns={[0, 1]}
/>

### Border radius

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

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

<StaticTable
  headers={[
    'Spectrum 1',
    'Spectrum 2'
  ]}
  rows={[
    ["'xsmall'", "'[1px]'"],
    ["'small'", "'sm'"],
    ["'regular'", "'default'"],
    ["'medium'", "'lg'"],
    ["'large'", "'xl'"]
  ]}
  codeColumns={[0, 1]}
/>

### 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:

<StaticTable
  headers={[
    'Spectrum 1',
    'Spectrum 2'
  ]}
  rows={[
    ["'size-0'", 0],
    ["'size-10'", 1],
    ["'size-25'", 2],
    ["'size-40'", 3],
    ["'size-50'", 4],
    ["'size-65'", 5],
    ["'size-75'", 6],
    ["'size-85'", 7],
    ["'size-100'", 8],
    ["'size-115'", 9],
    ["'size-125'", 10],
    ["'size-130'", 11],
    ["'size-150'", 12],
    ["'size-160'", 13],
    ["'size-175'", 14],
    ["'size-200'", 16],
    ["'size-225'", 18],
    ["'size-250'", 20],
    ["'size-275'", 22],
    ["'size-300'", 24],
    ["'size-325'", 26],
    ["'size-350'", 28],
    ["'size-400'", 32],
    ["'size-450'", 36],
    ["'size-500'", 40],
    ["'size-550'", 44],
    ["'size-600'", 48],
    ["'size-675'", 54],
    ["'size-700'", 56],
    ["'size-800'", 64],
    ["'size-900'", 72],
    ["'size-1000'", 80],
    ["'size-1200'", 96],
    ["'size-1250'", 100],
    ["'size-1600'", 128],
    ["'size-1700'", 136],
    ["'size-2000'", 160],
    ["'size-2400'", 192],
    ["'size-3000'", 240],
    ["'size-3400'", 272],
    ["'size-3600'", 288],
    ["'size-4600'", 368],
    ["'size-5000'", 400],
    ["'size-6000'", 480],
    ["'static-size-0'", 0],
    ["'static-size-10'", 1],
    ["'static-size-25'", 2],
    ["'static-size-40'", 3],
    ["'static-size-50'", 4],
    ["'static-size-65'", 5],
    ["'static-size-100'", 8],
    ["'static-size-115'", 9],
    ["'static-size-125'", 10],
    ["'static-size-130'", 11],
    ["'static-size-150'", 12],
    ["'static-size-160'", 13],
    ["'static-size-175'", 14],
    ["'static-size-200'", 16],
    ["'static-size-225'", 18],
    ["'static-size-250'", 20],
    ["'static-size-300'", 24],
    ["'static-size-400'", 32],
    ["'static-size-450'", 36],
    ["'static-size-500'", 40],
    ["'static-size-550'", 44],
    ["'static-size-600'", 48],
    ["'static-size-700'", 56],
    ["'static-size-800'", 64],
    ["'static-size-900'", 72],
    ["'static-size-1000'", 80],
    ["'static-size-1200'", 96],
    ["'static-size-1700'", 136],
    ["'static-size-2400'", 192],
    ["'static-size-2600'", 208],
    ["'static-size-3400'", 272],
    ["'static-size-3600'", 288],
    ["'static-size-4600'", 368],
    ["'static-size-5000'", 400],
    ["'static-size-6000'", 480],
    ["'single-line-height'", 32],
    ["'single-line-width'", 192]
  ]}
  codeColumns={[0, 1]}
/>

### Break points

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

<StaticTable
  headers={[
    'Spectrum 1',
    'Spectrum 2'
  ]}
  rows={[
    ['base', 'default'],
    ['S', 'sm'],
    ['M', 'md'],
    ['L', 'lg']
  ]}
  codeColumns={[0, 1]}
/>