Upgrading to 2.0
Move an application from Siteplane UI 1.x to 2.0, with the new size steps, the removed names, the changed defaults and the reinstall.
Siteplane UI 2.0 puts every control on one size scale in steps of 4 px and gives the basic controls new spacing and structure in the kit's own look. Its icons are Phosphor, the text Button variant is gone, and sixteen components join the kit. The kit's own texts come from one set of messages, so you translate them in one place. A control without a size keeps its height, so most screens change little. Code that names sizes, the names on this page, a style on a field and tests of the loading, copy and menu states need changes. Installed source changes only when you install again, so you choose when 2.0 reaches your application. The changelog lists every change.
Reinstall every item
Commit your work, then look at what an item will change:
pnpm dlx shadcn@4.18.0 add @siteplane/button --diffThe items of a release work together, so reinstall every Siteplane UI item your application uses in one command, and your Siteplane UI Pro patterns the same way under @siteplane-pro:
pnpm dlx shadcn@4.18.0 add @siteplane/button @siteplane/input @siteplane/select @siteplane/dialog --overwriteThe registry installs @phosphor-icons/react with the components that use it and no longer lucide-react. Remove lucide-react from package.json once your own code no longer imports it, and set "iconLibrary": "phosphor" in components.json, as Installation shows. Phosphor does not hide an icon from assistive technology on its own, so a decorative icon of yours takes aria-hidden="true":
import { BellIcon } from "lucide-react";
<BellIcon />;import { BellIcon } from "@phosphor-icons/react/dist/ssr";
<BellIcon aria-hidden="true" />;Update the agent skill as described in Skills, so your agent writes 2.0 code. To stay on 1.x for now, install the fixed source of 1.8.1 as described in Pin a release.
Sizes
| Size | 1.x | 2.0 |
|---|---|---|
xs | 24 px | 32 px |
sm | 28 px | 36 px, the default |
md | 32 px | 40 px |
lg | 36 px, the default | 44 px |
xl | 48 px | 48 px |
The default moved from lg to sm and kept its 36 px, so a control without a size keeps its height. A size you set, and the controlSize of a provider, now name a taller step. To keep a Button's 1.x height, use the size of the same height:
| 1.x | Height | 2.0 |
|---|---|---|
xs | 24 px | xs, 32 px; no text Button is smaller |
sm | 28 px | xs, 32 px |
md | 32 px | xs |
lg, the default | 36 px | sm, the default, or no size |
xl | 48 px | xl |
icon-2xs | 20 px | icon-2xs, 24 px |
icon-xs | 24 px | icon-2xs |
icon-sm | 28 px | icon-xs, 32 px |
icon-md | 32 px | icon-xs |
icon-lg, the default | 36 px | icon-sm, the default, or no size |
icon-xl | 48 px | icon-xl |
<SiteplaneUIProvider controlSize="lg">
<Button size="sm">Edit</Button>
<Button aria-label="Remove" size="icon-md">
<TrashIcon aria-hidden="true" />
</Button>
</SiteplaneUIProvider><SiteplaneUIProvider>
<Button size="xs">Edit</Button>
<Button aria-label="Remove" size="icon-xs">
<TrashIcon aria-hidden="true" />
</Button>
</SiteplaneUIProvider>- Provider:
controlSize="lg"onSiteplaneUIProviderbecomescontrolSize="sm", or leave it out. WithcontrolSize="sm"or"md", controls are now 36 or 40 px high, and no field is smaller than 36 px. - Controls from 36 px: fields, Toggle, Toggle Group, Select Button and Color Swatch Picker start at
sm, 36 px. Check narrow layouts, since a row of compact controls grows: a Toggle Group item atsmhas 14 px at either side of its label, where it had 6 px. Items withgrowshare the row and come down to 6 px before the row overflows. - Relative sizes:
useRelativeControlSizecounts from the defaultsm. Pass the size the part has atsm: a compact part that wasuseRelativeControlSize("sm"), 28 px beside 36 px controls, isuseRelativeControlSize("xs"), 32 px. See Control size. - CSS: the control tokens follow the new scale, so
--sp-rw-control-lgis 44 px. Read--sp-rw-control-smfor the 36 px default, for exampleh-(--sp-rw-control-sm). See Shared dimensions. - Selectors: Buttons and fields write their size to
data-size, and a control without asizewritessm, where it wrotelg. CSS of yours that selects[data-size="lg"]for the default control now matches only 44 px controls, so select[data-size="sm"]for it.
Components with steps of their own
- Badge:
smtoxlare 22, 24, 28 and 32 px, where they were 16, 20, 24 and 28 px, and a Badge without a size is 22 px instead of 24. Usemdfor 24 px andlgfor 28 px; no Badge is smaller than 22 px. - Calendar: the days are 32 px at
xs, 40 px atsm, the default, 48 px atmd, 52 px atlgand 56 px atxl, where they were 28 px atxs, 32 px atsm, 40 px atmdand at the defaultlg, and 48 px atxl. A Calendar atmdor without a size keeps its 40 px without a size, one atsmkeeps its 32 px atxs, and one atxlkeeps its 48 px atmd. There is no 28 px step, so a Calendar atxsgrows from 28 to 32 px. A Calendar takesxsonly from its ownsize, never from the provider. See Calendar sizes. - Avatar Group: the sizes moved one name down.
xsis 24 px,sm32 px and the default, thenmd40,lg48,xl56 and2xl64 px. In 1.x,smwas 24 px and the defaultmd32 px. - Checkbox, Radio and Switch: the boxes are 16, 20, 24 and 28 px, 16 px by default where it was 18. The Switch is 36 by 20 px by default, where it was 36 by 22.
- Slider: the thumb is as large as the Switch thumb of the same size, 16, 20, 24 and 28 px from
smtoxl, on rails of 6, 8, 8 and 10 px, where the thumbs were 14, 16, 18 and 20 px on rails of 4, 6, 8 and 10 px. A Slider without a size has a 16 px thumb on a 6 px rail, where it had 18 px on 8 px. - Table and Native Table: the default
smhas a 36 px heading row, rows of at least 56 px and 12 px above and 20 px beside each cell. The dense table of 1.x issize="xs": a 32 px heading row, 4 and 8 px of cell padding and rows as tall as their content. See Table sizes.
<Badge size="lg">Beta</Badge>
<AvatarGroup size="sm">{/* … */}</AvatarGroup>
<Table aria-label="Payments" size="sm">{/* … */}</Table>
<Calendar aria-label="Booking date" size="sm" /><Badge size="md">Beta</Badge>
<AvatarGroup size="xs">{/* … */}</AvatarGroup>
<Table aria-label="Payments" size="xs">{/* … */}</Table>
<Calendar aria-label="Booking date" size="xs" />Removed, renamed and changed
The text variant
text was a second name for the link and is removed. Use link on Button; on ExpandingArrowButton, link is the default.
<Button variant="text">Show all</Button>
<ExpandingArrowButton label="Read the guide" variant="text" /><Button variant="link">Show all</Button>
<ExpandingArrowButton label="Read the guide" />Menu checkbox rows
MenuCheckboxItem, DropdownMenuCheckboxItem and ContextMenuCheckboxItem no longer take size, which sized the switch. A switch row draws the standard Switch at the size of the row.
<DropdownMenuCheckboxItem size="sm" variant="switch">
Daily digest
</DropdownMenuCheckboxItem><DropdownMenuCheckboxItem variant="switch">
Daily digest
</DropdownMenuCheckboxItem>switchVariants and switchMenuTrackClassName are removed with it. switchTrackClassName is the composition string of a menu row's track, beside switchThumbClassName:
const track = switchVariants({ size: "lg" });
const menuTrack = switchMenuTrackClassName;const track = switchTrackClassName;The check of a chosen row
The check of a chosen row ends the row in Select, Combobox, List Box and every menu, and it follows the label in the markup. indicatorPosition="end" is the default now, so remove it; indicatorPosition="start" puts the check first, as in 1.x. The box of a multiple Select, a multiple Combobox and a checkbox row still leads its row.
<DropdownMenuRadioItem indicatorPosition="end" value="owner">
Owner
</DropdownMenuRadioItem><DropdownMenuRadioItem value="owner">Owner</DropdownMenuRadioItem>Radio rows close their menu
A radio row closes its menu when it is picked, in Menu, Dropdown Menu and Context Menu, and a radio row of a Drawer Menu closes its drawer. In 1.x they kept it open, so a radio row that closed its menu with closeOnClick no longer needs it, and a menu that should stay open after a pick takes closeOnClick={false} on its radio rows. Check rows stay open, and a switch row never closes its menu.
<MenuRadioGroup onValueChange={setModel} value={model}>
<MenuRadioItem closeOnClick value="fast">
Fast
</MenuRadioItem>
<MenuRadioItem closeOnClick value="thorough">
Thorough
</MenuRadioItem>
</MenuRadioGroup><MenuRadioGroup onValueChange={setModel} value={model}>
<MenuRadioItem value="fast">Fast</MenuRadioItem>
<MenuRadioItem value="thorough">Thorough</MenuRadioItem>
</MenuRadioGroup>Featured Icon
Featured Icon is a component of its own, and Notification no longer exports it. Reinstalling Notification installs it, or add @siteplane/featured-icon. Import FeaturedIcon and FeaturedIconTone from it, and pass the glyph as children instead of icon. Without a size it keeps the 36 px box, the 18 px glyph and the pulsing rings of 1.x.
import { FeaturedIcon } from "@/siteplane/components/notification";
<FeaturedIcon icon={BellIcon} tone="accent" />;import { FeaturedIcon } from "@/siteplane/components/featured-icon";
<FeaturedIcon tone="accent">
<BellIcon aria-hidden="true" />
</FeaturedIcon>;Native date and time inputs
Input no longer styles the browser's date and time inputs, and its hidePickerIndicator prop is removed. For a date, use Date Field, which types it in segments and opens the kit's calendar, or Date Picker, which chooses it from that calendar behind a button. For a time, use Time Field. Each takes the Field's label, description and error, as Input does.
<Input hidePickerIndicator type="date" />
<Input type="time" /><DateField />
<DatePicker />
<TimeField />The time of a Date Time Picker
The field of a Date Time Picker types its time into its segments, as a Date Field with a time does, and ends with its calendar button. The time button, its list of hours and minutes and the comma the picker drew between the date and the time are gone; the separator of the locale stands there, a comma and a space in en-US. So openTimePickerLabel is removed, and minuteStep no longer sets a step for the field, whose segments take any minute: it sets the times of the panel that trigger="button" opens, every 30 minutes by default. Check a step on the server if it matters. Time Field keeps its button and its list.
<DateTimePicker
aria-label="Meeting start"
minuteStep={15}
openTimePickerLabel="Choose a time"
/><DateTimePicker aria-label="Meeting start" />
<DateTimePicker aria-label="Meeting start" minuteStep={15} trigger="button" />See Minute step.
Fields that fill their row
Number Field and Date Field fill their container, as Input does. width="fit" keeps the compact Number Field of 1.x. Time Field, Date Range Picker and Date Time Picker keep the width of their content, and width="full" fills the row in place of a width class. A Select trigger fills its container as before, and width="fit" on SelectTrigger or SelectButton makes it as wide as its value in place of a class such as w-fit min-w-0. Date Picker keeps the width of its date and Native Select fills its container, and each takes the other width with width="full" or width="fit".
<NumberField defaultValue={3} />
<TimeField className="w-full" />
<SelectTrigger className="w-fit min-w-0">
<SelectValue />
</SelectTrigger><NumberField defaultValue={3} width="fit" />
<TimeField width="full" />
<SelectTrigger width="fit">
<SelectValue />
</SelectTrigger>Field variants
The fields keep two surfaces, the default and soft. elevated and inset are removed from Input, Input Group, Textarea, Number Field, OTP Field, the date and time fields, the inputs of Combobox and Autocomplete, ComboboxChips, Prompt Input and Password Strength, and from SelectTrigger and SelectButton. inset drew the default field, and elevated added only the contour of an elevated Card around it; a Select trigger drew its default surface for both. Remove the prop or pass variant="default". soft stays on Input, Input Group, the date and time fields, File Input, Prompt Input and Password Strength, and every other field you type into takes it too, such as Textarea, Number Field, OTP Field, Tags Input and the inputs and chips of Combobox and Autocomplete. For a trigger in a filter bar or a toolbar, beside a search field, the new variant="outline" rests transparent inside the rim of an outline Button. SelectTrigger, SelectButton, Native Select, Date Picker, the Button trigger of Date Range Picker and Date Time Picker, and Color Picker take it. formControlSurfaceClassNames and the shadow-form-control class are gone with them, so CSS of yours keyed on that class, on a field's data-variant="elevated" or "inset" or on a trigger's data-profile-mode of those names matches nothing. Remove it.
<Input aria-label="Search" variant="elevated" />
<SelectTrigger variant="inset">
<SelectValue />
</SelectTrigger><Input aria-label="Search" />
<SelectTrigger>
<SelectValue />
</SelectTrigger>The className and style of a field
className and style style the field you lay out, its outer element, on every field. Input and Textarea sent style to the native control in 1.x and now send it to their outer span with className, so a margin or a width in style moves the whole field. Input's style takes an object, no longer a function of the input's state. ComboboxInput and AutocompleteInput send both to the group that holds the input with its trigger, its clear button and its start addon, where className reached the input's box and style the input, and CommandInput's className follows. A style meant for the text inside moves to className with a child selector. The style of InputGroupInput, InputGroupSegment and InputGroupTextarea still reaches their native control.
<Input aria-label="Amount" style={{ textAlign: "end" }} /><Input aria-label="Amount" className="[&_input]:text-end" />See Input.
Sticky table headers
The heading row of Table and Native Table sticks to the top of its scrolling container only with stickyHeader; in 1.x it always did. Add stickyHeader where a table keeps its heading row in view. With it, a table in a parent of a fixed height, such as a card or a panel, takes at most that height, so it needs no height class there.
<Table aria-label="Payments" containerClassName="max-h-80"><Table aria-label="Payments" containerClassName="max-h-80" stickyHeader>Sticky bars in a Dashboard Shell
On a phone the Dashboard Shell's header is 56 px high, where it was 48 px, and it stays in view over the page. A sticky bar of your own in DashboardShellMain takes --sp-dashboard-shell-header-offset as its top in place of an offset of its own: the shell sets it to 56 px below the breakpoint, where the header sticks over the page, and to 0 where the main area scrolls on its own. See Sticky header.
<div className="sticky top-12 md:top-0">{/* toolbar */}</div><div className="sticky top-(--sp-dashboard-shell-header-offset)">
{/* toolbar */}
</div>Round skeletons
shape="circle" on Skeleton rounds it fully, for the placeholder of an avatar or a status dot, in place of a rounded-full class.
<Skeleton className="size-10 rounded-full" /><Skeleton className="size-10" shape="circle" />Popover headers
PopoverDescription no longer keeps 4 px above itself after a PopoverTitle. Put the two in PopoverHeader, which keeps them 4 px apart, as the header of a Dialog does, and remove a wrapper of your own that spaced them with a gap or a margin. Both stand on a 20 px line, where they stood on 21 px.
<PopoverPopup>
<div className="grid gap-1">
<PopoverTitle>Snooze until</PopoverTitle>
<PopoverDescription>The thread returns to your inbox.</PopoverDescription>
</div>
</PopoverPopup><PopoverPopup>
<PopoverHeader>
<PopoverTitle>Snooze until</PopoverTitle>
<PopoverDescription>The thread returns to your inbox.</PopoverDescription>
</PopoverHeader>
</PopoverPopup>See Popover.
The Page Header photo
The page-header-avatar-badge slot is removed. The badge of Page Header's avatar is the avatar's corner mark, an AvatarBadge that the avatar sizes and places, 24 px on the 96 px photo over a banner, 32 px on the 160 px one and 18 px on the 56 px avatar beside the title. A size on the verified Badge no longer changes it, so remove it. Over a banner the photo is the Avatar's profile photo, with a hairline ring and a gap in the header's color that cuts it out of the cover.
<PageHeader
avatar={{
alt: "Mara Ellis",
badge: (
<Badge profile="verified" size="lg">
<CheckIcon aria-hidden="true" />
<span className="sr-only">Verified</span>
</Badge>
),
initials: "ME",
src: "/avatars/mara.webp",
}}
banner
title="Mara Ellis"
/><PageHeader
avatar={{
alt: "Mara Ellis",
badge: (
<Badge profile="verified">
<CheckIcon aria-hidden="true" />
<span className="sr-only">Verified</span>
</Badge>
),
initials: "ME",
src: "/avatars/mara.webp",
}}
banner
title="Mara Ellis"
/>See Banner.
Remove names of tags
A Tag's remove button has one name of its own, "Remove" and the tag, such as "Remove Design", where 1.x read "Remove tag" and the tag. A removeLabel is now that whole name, where 1.x put the tag after it, so a label of your own names the tag too:
<Tag key={tag} onRemove={() => remove(tag)} removeLabel="Delete">
{tag}
</Tag><Tag key={tag} onRemove={() => remove(tag)} removeLabel={`Delete ${tag}`}>
{tag}
</Tag>Header Navigation on a phone
backLabel is removed from HeaderNavigation: the links of a dropdown, and of a link with items, open in place under their row in the phone menu, so it has no Back button. Remove the prop. mobileVariant picks the menu of a narrow header: fullscreen, the default, as in 1.x, or default for the Sidebar's side sheet, which suits an application. See Mobile navigation.
<HeaderNavigation backLabel="Back" brand={brand} items={items} /><HeaderNavigation brand={brand} items={items} />
<HeaderNavigation brand={brand} items={items} mobileVariant="default" />Empty State spacing
Empty adds no space around itself; the surface it sits on gives that. Its title and description step with its new size: lg by default for a page, md for a card or a table and sm for a compact surface such as a popover. To keep the room of 1.x, give the Empty its padding:
<Empty>{/* EmptyHeader, EmptyContent */}</Empty><Empty className="px-6 py-24">{/* EmptyHeader, EmptyContent */}</Empty>See Empty State sizes.
Text on accent fills
Text and checks on an accent fill take --sp-rw-fg-on-accent, which came with 1.2: the label of the accent Button and Badge, the checks of Checkbox, Radio, Table selection and the checkbox rows, a selected Calendar day and, new in 2.0, text-primary-foreground. It defaults to --sp-rw-fg-emphasis, the white of destructive fills. Give a light brand its dark text in --sp-rw-fg-on-accent, in both theme scopes. An override of --sp-rw-fg-emphasis, as applications set it before 1.2, no longer reaches the accent fills inside an element of your own, and on :root it turns the text of destructive fills dark too.
:root {
--sp-rw-bg-accent: #facc15;
--sp-rw-fg-emphasis: #1c1917;
}:root,
:is(.light, [data-theme="light"]) {
--sp-rw-bg-accent: #facc15;
--sp-rw-fg-on-accent: #1c1917;
}
:is(.dark, [data-theme="dark"]) {
--sp-rw-bg-accent: #facc15;
--sp-rw-fg-on-accent: #1c1917;
}See Override component colors.
Removed deprecated names
2.0 removes the names that 1.x deprecated, as Stability and deprecations promised. TypeScript reports each one that your code still writes; a value that comes from data, such as a tone read from an API, needs the same change. Use the replacements:
| Removed | Use |
|---|---|
isActive on PaginationLink, PaginationPrevious, PaginationNext, SidebarMenuButton and SidebarMenuSubButton | active |
current on StepperButtonItem | active |
checked, defaultChecked and onCheckedChange on the theme toggles | pressed, defaultPressed and onPressedChange |
DetailDrawerContent | DetailDrawerPopup |
Badge variant="brand" | variant="accent" |
TimelineItem variant, and its default | tone, and neutral |
Meter tone default and destructive | accent and error |
TooltipPopup tone default and destructive | neutral and error |
ResourceListIndicator tone="muted" | tone="neutral" |
FeaturedIcon tone gray and brand | neutral and accent |
Notification tone gray, brand and default | neutral, accent and no tone |
ActivityFeedItem presence | status and statusLabel |
ModalBlock tone default and destructive | neutral and error |
onChange on the Modal date range parts, ModalImageCrop and ModalTextEditor | onValueChange |
ModalDateRangePresets | presets on ModalDateRangeFields |
<PaginationLink href="?page=2" isActive>
2
</PaginationLink>
<Badge variant="brand">New</Badge>
<TooltipPopup tone="destructive">Payment failed</TooltipPopup><PaginationLink active href="?page=2">
2
</PaginationLink>
<Badge variant="accent">New</Badge>
<TooltipPopup tone="error">Payment failed</TooltipPopup>The icon prop of FeaturedIcon and the FeaturedIcon of Notification go with them, as Featured Icon shows.
Behavior that tests notice
- Loading:
loadingno longer setsdisabled. The Button stays focusable, setsaria-busyandaria-disabled, and hides its spinner from assistive technology, so its accessible name is its label without "Loading". A test that expects a disabled button checksaria-disabledoraria-busyinstead. LoadingButton renders the Button without a wrapper element and showsloadingTextwhile its action runs. See Disabled and loading states. - Copy Button: a Copy Button with a label keeps the label and swaps only its icon. "Copied" and a failure are announced instead of shown. See With text.
- Icons: kit icons are Phosphor SVGs with
aria-hidden="true"and nolucide-*classes, so a selector for a Lucide class no longer finds them. - Menus: a radio row closes its menu, or its Drawer Menu's drawer, when it is picked, and so does an account row of HeaderAccountMenu; see Radio rows close their menu. A switch row keeps its menu open when it is pressed, whatever
closeOnClicksays, and check rows stay open, as in 1.x. - Choice rows: the rows of a multiple Select or Combobox show a checkbox box. A Combobox with chips takes a chosen option out of the list and closes once every option is chosen;
hideSelected={false}keeps them in the list. - Fields: an invalid Input, Input Group or date field shows an alert icon at its end;
showInvalidIcon={false}leaves it out. A Textarea inside a Field takes the Field's name and disabled state, as Input does. The popover of a date picker or of Color Picker keeps to the room beside its trigger and scrolls inside it, and it brings the day in focus into view. The calendar of a Date Field opens with the focus on its day, the value or today, where it started on the button for the previous month. A date or time segment is as wide as its text, so the first digit typed over a placeholder moves the segments after it. A Date Time Picker's field has one button, the calendar's, and takes its time typed into the segments, as The time of a Date Time Picker shows. - Names: a Tag's remove button reads "Remove" and the tag, such as "Remove Design", where 1.x read "Remove tag" and the tag, and a
removeLabelis its whole name, as Remove names of tags shows. The Breadcrumb ellipsis reads "More", and a date picker's trigger ends its name with the chosen value. The search field inside a Combobox popup, such as the one of a searchable select, is named by its ownaria-labelor "Search", where it took the label of its Field, also over anaria-labelof its own. - Keyboard and focus: Home and End move the focus to the first and last item of a Toolbar, and a field inside it keeps both keys. Closing a Notification moves the focus to the next element after it, as closing an Alert does.
- Tooltips: TooltipProvider opens the first tooltip after 300 ms, where it waited 700 ms, and keeps 550 ms for the next one. A tooltip stays a visual label;
describeTriggeron a Tooltip that adds information gives its popuprole="tooltip"and names it in its trigger'saria-describedbywhile it is open.describeTrigger="always"names it while the tooltip is closed as well. The help icon of a field works this way, so its button names the hidden popup inaria-describedbyat all times and no longer holds a hidden copy of the text; reinstalltooltipandinput-grouptogether. See Supporting text. - Payment fields: the card number of ModalPaymentFields keeps the blocks of its network, 4, 6 and 5 digits for American Express and 4, 6 and 4 for a Diners Club number that starts with 36, where every number stood in fours, and the expiry month stays between 01 and 12: a 4 becomes 04, and a digit that would make the month 00 or 13 is left out.
- Navigation: on a phone, Header Navigation's fullscreen menu opens under its bar and is not modal: the menu button stays in the tab order as its toggle and its close, Tab moves from it into the menu and Shift+Tab back, and Escape closes the menu and returns the focus to the button. A dropdown's links open in place under their row. The Sidebar's sheet starts with its close button, the first Tab stop, named "Close sidebar" or by
closeLabel, and a SidebarTrigger inside the sidebar renders nothing there. - Texts and locale: the kit's own texts read their English from the messages of SiteplaneLocaleProvider, so the words stay the same until you translate them, once, as Localization shows; the kit ships German as
@siteplane/messages-de. The date parts of Modal Block write their dates in the provider's locale, or the browser's language without one, where 1.x always wrote en-US. Task Calendar writes its dates and weekdays in the provider's locale and starts its week on the locale's first day, Sunday in en-US, where it always wrote en-US and started on Monday. Inside a provider, the charts, Bar List, Progress, Meter, Avatar Group, Motion Number, Number Field and Slider write their numbers in its locale, where 1.x wrote en-US, or the browser's language in Number Field and Slider, unless each got alocale; without a provider they stay as they were. A Spinner without a name of yours is named "Loading" by a hidden label inside it, where 1.x set anaria-label, so a test finds it by its role and name. - Charts: tooltip values and axis labels change at once instead of rolling. Pass
rollingNumbersto roll them. See Rolling numbers. - Motion:
MotionSwaprenders one pane and replaces its content at once, where the old content stayed and faded out over the new one, and only the height of its container follows; Stepper, Metric Card, Notification, File Upload, Prompt Input and the tabs of a Filter Bar switch this way. A test that waited for the old content to leave finds it gone at once. Every floating panel, such as a Popover, a Menu, a Select's list or the calendar of a Date Picker, opens in 150 ms and closes in 100 ms, where a Popover, a Menu or a Select's list took 240 ms each way and the popover of a date or color picker 160 ms to open and 150 ms to close. A Dialog or Alert Dialog opens and closes in 200 ms, where it took 210 ms. An Accordion's or a Collapsible's panel opens and closes in 200 ms on one curve and fades its content with it, where the Accordion took the state curve and the Collapsible a curve of its own, neither with a fade. The Tabs indicator glides in 250 ms, where it took 150 ms. A toast slides in over 350 ms and out over 250 ms, where it took 380 ms each way, and a Sheet or Drawer opens in 250 ms and closes in 200 ms, where a Sheet took 450 ms each way and a Drawer 450 ms to open and 400 ms to close. A test that waits for one of them waits less. The text of a Tooltip or Popover that moves to another trigger switches at once too, where the old text faded out over the new one, and a Navigation Menu cross-fades its panels where they stand, where they slid 12 px;--motion-navigation-distanceis gone with the slide. A List Box row shows its focus ring only for keyboard focus. See Replace content. - Tables: pressing a control inside a column heading no longer sorts the column, and the heading row scrolls with the rows unless the table has
stickyHeader. - Slots and classes: the close button of an Alert carries
data-slot="alert-close", where it carried the Button'sbutton. The parts of FilterBar carry slots of their own,filter-bar,filter-bar-controls,filter-bar-search,filter-bar-filters,filter-bar-active-filtersandfilter-bar-actions, beside theirdata-pattern, andDashboardShellPrimarycarriesdashboard-shell-primary.CommandShortcutcarriesdata-slot="command-shortcut"on a<kbd>of its own, where it was a Kbd withdata-slot="kbd"anddata-command-shortcut. The Date Time Picker'sdate-time-picker-time-trigger,date-time-picker-time-popover,date-time-picker-time-selectoranddate-time-picker-separatorand Page Header'spage-header-avatar-badgeare gone with their parts. The triggers of Date Picker and Color Picker carrydata-variant="default", where they carriedoutline, and a number or text inSidebarMenuBadgerenders a Badge inside it. Thesp-swap-fadeclass and its rules are gone, and the installedmotion-presence.tsno longer exportsswapPresence,SwapTiming,toMotionElementorswapFadeClassName; content that switches carriessp-panel-switch, as a Tabs panel does. The caret of HeaderAccountMenu'scardtrigger, as of Account Card, isMenuTriggerIcon variant="switcher", withdata-slot="menu-trigger-icon",data-variant="switcher"and the classsp-menu-trigger-icon, where it was an icon of its own.
What looks different
- Weights: Button labels are 450, where they took the text weight of 400, and links are 500, 50 above the Buttons. A chosen row of Select, Combobox and List Box keeps the weight of the other rows, where a chosen Select row took 450, so the check alone marks it. In a Calendar, the headings, today and the chosen day take the label weight, 500, where the month and year picker's heading, today and the chosen day took 560. See Typeface.
- Links: a link never rests underlined; the underline appears on hover and press. A link of the
inlineprofile takes the accent color, in a sentence and on its own beside text, such as View report at the foot of a card.profileTone="neutral"keeps the text color, as a Back link does. - Fields: a focused field draws a 1 px accent edge, also while the calendar or the list of one of its buttons is open, and an invalid field a 1 px error edge with the alert icon. A trigger that opens a list or a picker rests raised, as a Select trigger does, and a field you type into rests inset. Every trigger takes the hover and pressed tints of a Button, 4 % and 7 % in Light and 6 % and 10 % in Dark, where a Select trigger drew 4 % and 8 %. An icon laid over the input of a Toolbar is the field's icon, 16 px at
smand 20 px frommd, 8 px from the text, where it took the Toolbar's 20 px. The triggers of Date Picker and Color Picker, outline Buttons in 1.x, take the surface and the edges of a Select trigger and place their icon or swatch and their value as a field does, in the field's text at the regular weight. The glyphs in a field rest in the tertiary text color at 80 %, the caret of a Select, an icon that SelectValue renders, an icon in GroupText and the steppers of a Number Field included, where the steppers took the secondary color. Every disabled field fades to 50 % and lays a light gray fill under its text, as a disabled Input, Input Group and Textarea did in 1.x, and shows the not-allowed cursor over it; a Select trigger faded to 64 % without the fill. The line inside a field, such as the divider of an Input Group addon, takes the color of the field's edge. The selector of a Time Field follows the field's size: its rows are 36, 40, 44 and 48 px fromsmtoxl, where they were 32 px at every size, with 16 px text frommd, and Hours and Minutes are small group labels in the tertiary color. The list of times of a Date Time Picker follows its size too. See Field edges. - Rows and popups: menu rows are 36 px with the check at the end, options are as tall as their field, a one-line tooltip is 34 px, field labels stand 6 px above their control, and badges are 22 px by default. The check of a chosen row takes the accent color in every menu and list. A chosen List Box row takes the fill of the current Sidebar row, where it took the secondary fill, and its focus ring sits inside the row, for keyboard focus only. A highlighted Command row takes the lighter fill of a highlighted option, its shortcut is plain text, as in a Menu row, where it was a keycap, and the footer of a Command is the band of a Menu footer, with 14 px text in the quaternary color, where it held 12 px text. Toggles and the items of a Toggle Group rest in the text color of a Button and show that they are on by their fill, where they rested in the secondary text color.
- Chips and tags: the tags of a Tag Group and the chips of a Combobox stand on the surface of a default Badge with its hairline, white in Light, where a tag took the gray fill of a secondary Badge. A Tag's count keeps its gray box. In a field, the chips of a Combobox stand 6 px apart, where they stood 4 px apart, and the text starts 8 px after the last one.
- Chevrons: the down chevron of a trigger turns half a turn while its list, menu or panel is open, all with one motion, and is 16 px at every size: the caret of a Select, the chevron of a Navigation Menu trigger, which moved 1 px down in 1.x, an Accordion's and a Collapsible's, and
MenuTriggerIcon, the new chevron of a menu button, which replaces a chevron icon of your own. A chevron icon of your own stays still. Each draws Phosphor's CaretDown, the Select's caret too, where 1.x drew a narrower caret there. An up-down caret stays still: a switcher row of a Sidebar, such as a workspace switcher, ends withSidebarMenuChevron variant="switcher", and a menu button that switches accounts, workspaces or plans withMenuTriggerIcon variant="switcher", each in place of an up-down icon of your own. That caret, like the caret of an Account Card and of HeaderAccountMenu'scardtrigger, rests in the tertiary text color and takes the primary one on hover, press and while the menu is open, where the card trigger drew it in its text color. - Dots: the dots of a trigger that opens more actions are
OverflowGlyph, the dots in the Bold weight at 20 px, which replaces a dots icon of your own. The Breadcrumb ellipsis and the menu of a Metric Card draw it, where the Breadcrumb drew 16 px dots. - Groups and segments: a segment of an Input Group, such as a Select, Copy or Button segment, draws its divider unless you pass
divider={false}, where 1.x drew a divider only withdivider. Text before or after the value stands in the field without a cell or a line, as an Input Group's text of any length did in 1.x, such ashttps://,.com,EURor$, and now also GroupText beside an Input in a Group, where it stood on a gray cell. The value starts 8 px after the text; passdividerto an addon to keep a line. GroupText among other controls, such as the Buttons of a pager, keeps its gray cell, with its text centered, and among default Buttons the cell takes their edge where it forms the outside of the group, where it drew none. The prefix of ModalTextField and the username prefix of ModalProfileFields draw no divider, where they drew one. A Group joins its parts with one hairline: a GroupSeparator between Buttons with a rim lies on their rims, and a Group of outline Buttons draws the edge of a single outline Button, where it drew a ring in the color of a separator around the group. An outline Toggle Group keeps its pressed-in look. - Surface edges: the neutral edges are softer. Every surface draws one edge color,
--sp-rw-surface-edge, never weaker than a separator: in Light 17 % on 1x screens and 28 % on 2x and denser screens, where it was 24 % on both, and 40 % in Dark, where it was 52 %. Separators,--sp-rw-border-translucent, are 11 % and 28 %, where they were 16 % and 40 %. The rim of a default Button, a field and a Select trigger is 12 %, where it was 16 %, and the rim of an outline Button, Toggle or trigger 18 %, where it was 25 %; the edge of a Checkbox and a Radio keeps its strength. The surface edge reaches Cards, CardFrames, Frame panels, a raised Notification and the sidebars, and the default Alert draws it without a shadow, where it drew the separator color. An inset Card in Dark draws 40 %, where it drew 24 %; if you set--sp-rw-surface-inset-shadowon:rootand nest a Dark scope, set it in the Dark scope too. To draw every line 1 px wide on every screen, in the colors of a 1x screen, passhairline={false}to SiteplaneUIProvider, as Hairline shows. A message Card, an outline Bubble, a Code Block, an Attachment, a choice card at rest, an icon well and the frame of a Task Calendar draw it as their border, where they drew the separator color. Inline Code, Kbd and dividers keep the separator color. See Surface edges. - Date and time fields: a segment is as wide as its text, so the separators stand at the same distance from the digits in every locale, such as tt.mm.jjjj in German, where segments of a fixed minimum width left uneven gaps. A separator keeps its spaces, so a Czech date reads 01. 10. 2026 and a Hungarian one 2026. 10. 01., where 1.x dropped them.
- Alerts: an inline Alert places its action by its own width, as a banner and a band do: beside the text from 32rem of the Alert's width and under it in a narrower Alert, such as one in a drawer, where 1.x followed the width of the window. The title and description of every Alert stand on a 20 px line, where they stood on 21 px. See With actions.
- Slider: the thumb is as large as the Switch thumb of its size, 16 px on a 6 px rail without a size. See Components with steps of their own.
- Navigation: underline tabs are 32 px at the default size. The default Pagination puts Previous and Next at the ends as links with arrows, centers the pages and fills the current one. A count in a Sidebar row is a small secondary Badge, where it was a bare figure in the row's text color: pass a number or a text to
SidebarMenuBadge, and put an element of your own, such as an animated number, in aBadge size="sm" variant="secondary". Sidebar group labels take the tertiary text color. HeaderAccountMenu opens with its header band only from the avatar trigger, and its account rows show 20 px avatars, where they showed 24 px. Its avatar trigger shows a 32 px avatar in its 36 px button, where the avatar filled it, and itscardtrigger shows the account as an Avatar Label Group with a 40 px avatar, as Account Card does. - On a phone: Header Navigation and the Dashboard Shell show a bar 56 px high, where Header Navigation's was 64 px and the Dashboard Shell's 48 px, and Header Navigation keeps 16 px at either side, where it kept 20 px. Header Navigation's menu button is
MenuIconMorph, whose bars turn into the close, and its links are Sidebar rows. On a phone SidebarTrigger is a 40 px icon button with a menu glyph, and the Sidebar's sheet starts with a 56 px row with its close button at the end; a SidebarTrigger inside the sidebar stays out of the sheet, so remove a close button of your own from it. The bars of aMenuIconMorphare those of the menu glyph, 15 px long, 5 px apart and 1 px thick at every size, where they were 18 to 27.5 px long and 1.5 or 2 px thick, and it shows the hover fill of a ghost icon button. The text rows of a fullscreen Sheet menu rest in the secondary text with the rows' hover fill. - Overlays: Sheet, the side Drawers and Detail Drawer are 400 px wide, where they were 448; pass
className="max-w-md"to the popup for 448 px. Dialogs have a 24 px header and 16 px before their actions, actions stand 12 px apart, and the corner close is 40 px in a Dialog and 36 px in a Sheet. The Detail Drawer has the look of a Sheet: it floats on the Sheet's shadow without an edge line, its header has no hairline under it, and its body keeps 24 px from every side, where it kept 16 px above and below. An Alert Dialog takes the corners of a Dialog, 16 px at the default radius, where it took 24 px, and so does an inset Sheet, where it took 18 px. A Preview Card draws the surface of a Popover, and the title and description of a Popover stand on a 20 px line. - Cards: the footer of a Frame and of a Card Frame is a row, as a Card's is, so its parts stand side by side, centered, and the actions in the footer of a Card, a Frame or a Card Frame stand 12 px apart without a gap class, as in a Dialog, where they touched; a gap class of yours still sets the gap. Drop
flexanditems-centerfrom theclassNameofFrameFooterandCardFrameFooter, give a single child that fills the widthflex-1, and wrap parts that should stack in an element of their own. The title of a Card header stands 4 px above its description, where it stood 6 px above it. See Footer actions. - Calendar: Previous, Next and the month heading are as tall as a day, 32, 40, 48, 52 and 56 px from
xstoxl, as in the month and year picker, where they were Buttons of the default height at every size of the Calendar. So a Calendar, and the popover of a date picker, is 4 px taller at the default size and 12 to 20 px taller frommd. The heading keeps 8 px inside its edges and writes the Calendar's 14 px text, and a Calendar marks today with a dot. - Data: tables are roomier by default, and the tables in rendered Markdown are compact. Empty States have a larger title and
mdactions at their default size. A Resource List's dot is 8 px, where it was 6 px, its neutral dot takes the full muted gray, and aringand the disc of an icon indicator take the solid colors of a dark Featured Icon. The unread dot of an Activity Feed takes the green of a status dot, and the count of an Avatar Group grows with the group's size. - Colors: success takes the green and warning the amber of their status dots, so warning no longer reads as orange. Info takes the accent color:
text-info,bg-infoandtext-info-foregroundfollow it, and so do the info icons of Alert and Toast, the info dot of a Resource List and the info marker of a Timeline, which now looks like itsaccentmarker. Every status glyph takes the tone of its status dot in both themes, while status text keeps the text colors. The icons of Alert and Toast readtext-success,text-warning,text-destructiveandtext-infoas in 1.x. A Timeline marker, a Featured Icon's outline, which was a Notification's icon, the check and the cross of CopyButton, the lock of a blocked Stepper step and the status icons of the Patterns took the color of status text and now take the dot tones too, lighter in Light and a step deeper in Dark.--sp-semantic-color-primary(bg-primary,--primary,ring-primary) aliases the accent fill and--sp-semantic-color-primary-foregroundthe text on it, where they were a navy and white, so your own primary utilities draw the accent, and so does today in a Task Calendar.--sp-semantic-color-destructiveand-control(bg-destructive,bg-control) alias the fills of the destructive and default Button, where they were Tailwind's red and white or a near-black, and-primary-hover,-destructive-hoverand-control-hover(bg-primary-hoverand its siblings) the fills of the accent, destructive and default Button on hover, where they were fixed Tailwind colors; the theme files no longer set them. The error icon of Alert and Toast, the dot of an error Badge and the busy dot of an Avatar take the destructive Button's red, a little darker than Tailwind's, and so does every other color of yours that reads--destructive.--sp-semantic-color-destructive-foreground(text-destructive-foreground),-invalid(border-invalid) and-invalid-muted(bg-invalid-muted) alias the error family's text, fill and tint, and-warning-foregroundthe warning text, where they named Tailwind colors:invalidis the error fill in both themes, about 5 L darker in Light and 7 L in Dark,invalid-mutedis its tint, a red tint in Dark where it was a gray, and the error text keeps its color in Light and is 5.75 L lighter and a little paler in Dark.--sp-semantic-color-focus(ring-focus,outline-focus) aliases--sp-rw-border-focus, the color of every focus ring, so the focus of a Calendar day and of the Color Picker's thumbs no longer draws a fixed blue.--state-selected(bg-state-selected) is the selected fill of the rows, black at 5 % in Light and white at 6 % in Dark, where it was a tint of the navy, so a selected Resource List row looks the same with or withoutinteractive. To keep a color of 1.x, set the token after the base import in both theme scopes, as Override component colors shows. The page and the default Button are darker in Dark. See Status colors. - Colors inside controls: Button, Input, Input Group, Textarea and Switch read the theme's colors and keep no copies of their own, so text inside them that takes the foreground colors matches the text around them. In Light it is #030303 where 1.x drew #262626, and muted text, such as an Input Group's addon text, is #636363 where it was #686868; in Dark the two are #efefef and #878787, where they were #f5f5f5 and #818181.
- Details: Buttons other than links, Toggles, pressable Badges and selectable Tags flash their edge when a press ends;
data-flash={false}leaves a Button out. Icons are Phosphor in the Regular weight. Badges take the corner radius of their size, avatar initials are larger, and the Spinner turns with its solid head in front. A bordered profile photo, from3xl, paints the gap of its ring in the color of its surface, as the photos of Page Header and ModalUserSettings do. The remove button of a File Upload row is a 24 px icon action in the tertiary color, where it was a 36 px ghost Button, and a disabled Editable fades, its pencil included. Content that replaces content switches at once, the axis labels and grid lines of a chart and the pencil of an Editable included, and floating panels, dialogs and the items of a flow list move on the gentlereasecurve, where they took a curve that covered three quarters of the way in the first fifth of its time. A Popover, a Menu, a Select's list, a Tooltip or the popover of a date or color picker opens in 150 ms, growing from 95 % as it travels 4 px, and closes in 100 ms, so its text no longer lingers after its surface; it took 240 ms each way from 95.5 % and 7 px, and a picker's popover grew from 98 %. A Dialog or Alert Dialog on a wide screen grows from 95 % over 200 ms, where it grew from 98 % over 210 ms, and a tag or a chip that is added grows from 80 % around its center, where it grew from 96 %.
A worked example
An application with a customer list, an inbox, settings pages and an assistant moved to 2.0 with these changes:
- It reinstalled every item and replaced its Lucide imports with Phosphor ones, adding
aria-hidden="true"to decorative icons. Its dots icons becameOverflowGlyph, and the chevrons of its menu buttonsMenuTriggerIcon. - Where its views were dense, it kept the 1.x heights: Buttons
smandmdbecamexsandlgbecamesm, icon Buttonsicon-mdbecameicon-xsandicon-xsbecameicon-2xs, Badgesxlbecamelgandmdbecamesm, and its--sp-rw-control-lgheight classes read--sp-rw-control-sm. - Its data tables took
size="xs". variant="text"becamevariant="link", everyindicatorPosition="end"went, and icon-only Toolbar buttons tookshape="square".- Its shells took
containedin place of the frame classes. The window its sheets and dialogs portal into kept its transform, andSidebarMenulost itsgap-px. - Its Empty States took their padding on the host, and the ones inside its views
size="sm"; a compact Number Field tookwidth="fit". - Its loading skeletons took the 2.0 sizes, so a view no longer moved when it loaded, and its round placeholders took
shape="circle"in place ofrounded-full. - Its customer drawer took
DetailDrawerPopup, and the marks of its workspaces and companies becameAvatar shape="square". - Its workspace switcher ended with
SidebarMenuChevron variant="switcher", its account menu opened with aDropdownMenuHeaderthat holds an Avatar Label Group, and its inbox count, an animated number, went into aBadge size="sm" variant="secondary"insideSidebarMenuBadge. - Its snooze picker put its title and description in a
PopoverHeader, and its card footers dropped their gap classes.
Its 16 px count badges are 22 px now and its sm toggles 36 px. A row of seven day toggles with grow still fits a phone's column, because its items come down to 6 px of inset.