⚠️ S2 is currently in beta. APIs may change before the stable release. Pin your version and review the release notes when upgrading.

What changed in S2?

Spectrum 2 introduces a new visual language, updated design tokens, a consolidated package structure, and new components. It's a breaking change — but a gradual migration is possible by running v3 and S2 side by side.

📦

New package

S2 ships as a single @react-spectrum/s2 package instead of the per-component packages in v3.

🎨

New design tokens

Design tokens are generated from the new Spectrum 2 system using the style() macro instead of CSS modules.

⚙

Updated props

Some prop names and component APIs have changed (e.g. variant replaces isQuiet/isEmphasized on ActionButton).

Migration steps

1

Install the S2 package alongside v3

S2 uses a single package. You can install it without removing v3 to allow gradual migration.

npm install @react-spectrum/s2
2

Update imports

S2 exports components from the top-level package. Update your import paths:

v3 (before)

import {Button} from
  '@adobe/react-spectrum';
import {ComboBox} from
  '@react-spectrum/combobox';

S2 (after)

import {Button} from
  '@react-spectrum/s2';
import {ComboBox} from
  '@react-spectrum/s2';
3

Update ActionButton props

ActionButton's isQuiet and isEmphasized props are replaced by a unified variant:

v3

<ActionButton isEmphasized>
  Edit
</ActionButton>

S2

<ActionButton
  variant="accent">
  Edit
</ActionButton>
4

Adopt the style() macro

S2 uses a Parcel / webpack / Vite macro for design tokens. Instead of inline style props or CSS modules, wrap your styles with style():

import {style} from '@react-spectrum/s2/style' with {type: 'macro'};

<Button styles={style({marginTop: 'size-100'})}>
  Save
</Button>
5

Test both providers side by side

Wrap S2 components in Provider from @react-spectrum/s2. You can keep v3's Provider for unchanged components.

💡 Ask the AI assistant about specific components you're migrating — it can look up the exact v3 vs S2 prop differences from the live documentation.
Full migration guide ↗ Set up S2 now →