packages/dev/codemods/src/s1-to-s2/UPGRADE.md
Use the following guide to manually upgrade v3 React Spectrum components to use Spectrum 2.
Note that [PENDING] indicates that future changes will occur before the final release, and the current solution should be considered temporary.
@react-spectrum/s2 package instead of @adobe/react-spectrum or individual packages like @react-spectrum/buttonvariant=“cta” to variant="accent"variant=“overBackground” to variant=“primary” staticColor=“white”style to fillStyleisPending (it has not been implemented yet)isQuiet (it is no longer supported)href is present, Button should be converted to a LinkButtonelementType (it is no longer supported)isDisabled (it has not been implemented yet)size and instead provide a size via the style macro (i.e. styles={style({size: 20})})showRoot (it has not been implemented yet)isMultiline (it has not been implemented yet)autoFocusCurrent (it has not been implemented yet)size="S" (Small is no longer a supported size in Spectrum 2)showErrorIcon (it has been removed for accessibility reasons)size prop and set size via style macro insteadsize prop and set size via style macro insteadshowValueLabel (it has been removed for accessibility reasons)isQuiet (it is no longer supported)validationState=“invalid” to isInvalidvalidationState=“valid” (it is no longer supported)menuWidth value from a DimensionValue to a pixel valueisQuiet (it is no longer supported)loadingState (it has not been implemented yet)validationState=“invalid” to isInvalidvalidationState=“valid” (it is no longer supported)onLoadMore (it has not been implemented yet)UnavailableMenuItemTriggerDialog with ContextualHelpPopover, and child elements with their S2 counterparts.DialogTrigger to being a child of DialogonDismiss and use onOpenChange on the DialogTrigger, or onDismiss on the DialogContainer insteadDialogTriggertype=“tray” (Tray has not been implemented yet)mobileType=“tray” (Tray has not been implemented yet)targetRef (it is no longer supported)children to remove render props usage, and note that the close function was moved from DialogTrigger to DialogFlex to be a div and apply flex styles using the style macroisQuiet (it is no longer supported)isReadOnly (it is no longer supported)validationState (it is no longer supported)validationBehavior (it is no longer supported)Grid to be a div and apply grid styles using the style macrovariant=“info” to variant=“informative”variant=“overBackground” to staticColor=“white”density (it has not been implemented yet)dragAndDropHooks (it has not been implemented yet)closeOnSelect (it has not been implemented yet)targetKey (TODO: this may be a v3 bug or API differ bug)closeOnSelect (it has not been implemented yet)trigger (it has not been implemented yet)menuWidth value from a DimensionValue to a pixel valueisQuiet (it is no longer supported)validationState=“invalid” to isInvalidvalidationState=“valid” (it is no longer supported)isLoading (it has not been implemented yet)onLoadMore (it has not been implemented yet)variant=“overBackground” to staticColor=“white”labelPosition (it has not been implemented yet)showValueLabel (it has not been implemented yet)variant=“overBackground” to staticColor=“white”validationState=“invalid” to isInvalidvalidationState=“valid” (it is no longer supported)showErrorIcon (it has been removed for accessibility reasons)isQuiet (it is no longer supported)validationState=“invalid” to isInvalidvalidationState=“valid” (it is no longer supported)isFilled (Slider is always filled in Spectrum 2 design)trackGradient (Not supported in S2 design)showValueLabel (it has been removed for accessibility reasons)getValueLabel (it has not been implemented yet)orientation (it has not been implemented yet)showValueLabel (it has been removed for accessibility reasons)getValueLabel (it has not been implemented yet)orientation (it has not been implemented yet)isDisabled (it is no longer supported)variant=“info” to variant="informative"actionLabel (it has not been implemented yet)onAction (it has not been implemented yet)maxRows (it has not been implemented yet)errorMessage (it has not been implemented yet)isInvalid (it has not been implemented yet)validationState (isInvalid should be used when it becomes available)icon (it has not been implemented yet)isQuiet (it is no longer supported)validationState=“invalid” to isInvalidvalidationState=“valid” (it is no longer supported)icon (it has not been implemented yet)isQuiet (it is no longer supported)validationState=“invalid” to isInvalidvalidationState=“valid” (it is no longer supported)variant (it is no longer supported)placement and add to the parent TooltipTrigger insteadshowIcon (it is no longer supported)isOpen and add to the parent TooltipTrigger insteadplacement="bottom left" to be placement=“bottom”placement="bottom right" to be placement=“bottom”placement="bottom start" to be placement=“bottom”placement="bottom end" to be placement=“bottom”placement="top left" to be placement=“top”placement="top right" to be placement=“top”placement="top start" to be placement=“top”placement="top end" to be placement=“top”placement="left top" to be placement=“left”placement="left bottom" to be placement=“left”placement="start top" to be placement=“start”placement="start bottom" to be placement=“start”placement="right top" to be placement=“right”placement="right bottom" to be placement=“right”placement="end top" to be placement=“end”placement="end bottom" to be placement=“end”View to be a div and apply styles using the style macroMenu:
Item to be a MenuItemActionMenu:
Item to be a MenuItemTagGroup:
Item to be a TagBreadcrumbs:
Item to be a BreadcrumbPicker:
Item to be a PickerItemComboBox:
Item to be a ComboBoxItemListBox:
Item to be a ListBoxItemListView:
Item to be a ListViewItemTabList:
Item to be a TabTabPanels:
Item to be a TabPanel and remove surrounding TabPanelskey to be idMenu:
Section to be a MenuSectiontitle prop string to be a child of new Heading within a HeaderComboBox:
Section to be a ComboBoxSectiontitle prop string to be a child of new Heading within a HeaderPicker:
Section to be a ComboBoxSectiontitle prop string to be a child of new Heading within a HeaderReact 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.
Example:
- import {ActionButton} from '@adobe/react-spectrum';
+ import {ActionButton} from '@react-spectrum/s2';
+ import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
- <ActionButton marginStart="size-100">
+ <ActionButton styles={style({marginStart: 8})}>
Edit
</ActionButton>
Affected style props: borderWidth, borderStartWidth, borderEndWidth, borderTopWidth, orderBottomWidth, borderXWidth, borderYWidth.
Example:
- <View borderWidth="thin" />
+ <div className={style({borderWidth: 1})} />
Border widths should be updated to use pixel values. Use the following mappings:
| v3 | S2 |
|---|---|
'none' | 0 |
'thin' | 1 |
'thick' | 2 |
'thicker' | 4 |
'thickest' | '[8px]' |
Affected style props: borderRadius, borderTopStartRadius, borderTopEndRadius, borderBottomStartRadius, borderBottomEndRadius.
Example:
- <View borderRadius="small" />
+ <div className={style({borderRadius: 'sm'})} />
Border radius values should be updated to use pixel values. Use the following mappings:
| v3 | S2 |
|---|---|
'size-0' | 0 |
'xsmall' | '[1px]' |
'small' | 'sm' |
'regular' | 'default' |
'medium' | 'lg' |
'large' | 'xl' |
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:
| v3 | S2 |
|---|---|
'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 |
Break points previously used in style props can be used in the style macro with updated keys. Use the following mappings:
| v3 | S2 |
|---|---|
base | default |
S | sm |
M | md |
L | lg |
Example:
- <View width={{ base: 'size-2000', L: 'size-5000' }} />
+ <div className={style({width: {default: 160, lg: '[400px]'}) />