Skip to main content

The Strapi Design System has been upgraded to v2

The Strapi Design System  has been completely updated in Strapi 5 with significant changes to component structure, APIs, and usage patterns.

This page is part of the breaking changes database and provides information about the breaking change and additional instructions to migrate from Strapi v4 to Strapi 5.

 Is this breaking change affecting plugins?Yes
 Is this breaking change automatically handled by a codemod?No

Breaking change description​

In Strapi v4

Strapi Design System v1 used a specific approach with direct imports, styled-components v5, and certain component APIs that have since been revised.

In Strapi 5

Strapi Design System v2 has been completely updated with a focus on accessibility, API consistency, and better typing support. Major changes include:

  • Root imports instead of direct component paths
  • Styled-components upgraded to v6
  • Many components migrated to Radix-UI primitives
  • New Field API for form elements
  • TypeScript definitions now included
  • Several components renamed or removed

Migration​

This section regroups useful notes and procedures about the introduced breaking change.

Notes​

  • For detailed migration information, refer to the Design System migration guide .
  • The base font-size for the app is now 62.5% (10px), so 1rem = 10px.
  • Many icons have been updated or replaced.

Key changes to be aware of include the following:

Import structure changes​

- import { Combobox } from '@strapi/design-system/Combobox';
+ import { Combobox } from '@strapi/design-system';

ThemeProvider migration​

- import { ThemeProvider } from '@strapi/design-system';
+ import { DesignSystemProvider } from '@strapi/design-system';

Field components API changes​

- return <SingleSelect label={label} error={error} required={required} value={value} onChange={handleChange} />;
+ return (
+   <Field.Root error={error} required={required} name={name}>
+     <Field.Label>{label}</Field.Label>
+     <SingleSelect value={value} onChange={handleChange} />
+     <Field.Error />
+     <Field.Hint />
+   </Field.Root>
+ );

Grid component structure​

- import { Grid, GridItem } from '@strapi/design-system';
+ import { Grid } from '@strapi/design-system';

- <Grid gridCols={4}>
-   <GridItem col={2}>1</GridItem>
-   <GridItem col={2}>2</GridItem>
- </Grid>
+ <Grid.Root gridCols={4}>
+   <Grid.Item>1</Grid.Item>
+   <Grid.Item>2</Grid.Item>
+ </Grid.Root>

Component changes summary​

  • Renamed components: ToggleInput → Toggle
  • Removed components: Icon, Stack, ToggleCheckbox, Select/Option/OptGroup/SelectList (use SingleSelect or MultiSelect instead)
  • Layout components moved to CMS: Layout, MainNav, HeaderLayout, TwoColsLayout, GridLayout, ActionLayout, ContentLayout
  • New prop naming: as is now tag for polymorphic components
  • Radix-UI migrations: Many components including Accordion, Avatar, Checkbox, Dialog, Modal, Popover, Radio, Tabs, Tooltip

Manual procedure​

There is no codemod for this migration. Users will need to manually:

  1. Update all Design System imports to use root imports.
  2. Migrate component usages to the new APIs.
  3. Update icon usage.
  4. Replace Layout components with imports from @strapi/admin/strapi-admin.
  5. Update styling to account for the new base font size.