Strapi Design System

https://github.com/strapi/design-system
Admin
Strapi Design System provides guidelines and tools to help make Strapi's contributions more cohesive...
Tokens:34,254
Snippets:529
Trust Score:9.8
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install dependencies and start Storybook

Source: https://github.com/strapi/design-system/blob/main/CONTRIBUTING.md

Install dependencies, build the project, and start Storybook on localhost:6006 for development.

```bash
yarn install
yarn build
yarn develop
```

--------------------------------

### Install @strapi/ui-primitives with yarn or npm

Source: https://github.com/strapi/design-system/blob/main/packages/primitives/README.md

Install the package using either yarn add or npm i. The command is shown in a shell block with both options.

```shell
yarn add @strapi/ui-primitives

# or

npm i @strapi/ui-primitives
```

--------------------------------

### Install Strapi Design System with yarn or npm

Source: https://github.com/strapi/design-system/blob/main/README.md

Install the design system and its peer dependencies (react, react-dom, @strapi/icons, styled-components) using either yarn or npm. The command shows both alternatives with a comment separator.

```sh
$ yarn add react react-dom @strapi/design-system @strapi/icons styled-components

# or

$ npm install react react-dom @strapi/design-system @strapi/icons styled-components
```

--------------------------------

### Install Strapi Design System dependencies

Source: https://github.com/strapi/design-system/blob/main/docs/stories/00-getting started/welcome.mdx

Install the required packages for the Strapi Design System using yarn, npm, or pnpm. The command installs react, react-dom, @strapi/design-system, @strapi/icons, and styled-components.

```sh
$ yarn add react react-dom @strapi/design-system @strapi/icons styled-components

# or

$ npm i react react-dom @strapi/design-system @strapi/icons styled-components

# or

$ pnpm add react react-dom @strapi/design-system @strapi/icons styled-components
```

--------------------------------

### Responsive value shape examples

Source: https://github.com/strapi/design-system/blob/main/docs/stories/05-utilities/Helpers.mdx

Shows how a property can be a single value or an object keyed by breakpoint for responsive values.

```ts
// Single value
padding: 2

// Responsive object
padding: { initial: 1, medium: 2, large: 4 }
```

--------------------------------

### KeyboardKeys usage example

Source: https://github.com/strapi/design-system/blob/main/docs/stories/05-utilities/Helpers.mdx

Example of using KeyboardKeys to handle keyboard events with stable key values.

```tsx
import { KeyboardKeys } from '@strapi/design-system';

const handleKeyDown = (event: React.KeyboardEvent) => {
  if (event.key === KeyboardKeys.ESCAPE) {
    onClose();
  }
  if (event.key === KeyboardKeys.ENTER || event.key === KeyboardKeys.SPACE) {
    event.preventDefault();
    onSubmit();
  }
};
```

--------------------------------

### Select primitive usage example

Source: https://github.com/strapi/design-system/blob/main/docs/stories/02-primitives/overview.mdx

Shows the basic structure of the Select primitive from '@strapi/ui-primitives', including Root, Trigger, Value, Content, and Item components. This is the only code example on the page.

```tsx
import { Select } from '@strapi/ui-primitives';

// Primitives provide the structure and behavior
<Select.Root>
  <Select.Trigger>
    <Select.Value />
  </Select.Trigger>
  <Select.Content>
    <Select.Item value="option1">Option 1</Select.Item>
    <Select.Item value="option2">Option 2</Select.Item>
  </Select.Content>
</Select.Root>;
```

--------------------------------

### Link design system with yalc

Source: https://github.com/strapi/design-system/blob/main/CONTRIBUTING.md

Steps to publish the design system package with yalc and add it to a Strapi monorepo. Use the --pure option for monorepo setups. Do not commit these changes to the target repo.

```shell
cd packages/design-system # this could be icons too if you preferred.
yalc publish
cd ../../your-strapi-repo
yalc add @strapi/design-system --pure
```

--------------------------------

### Import Flex from @strapi/design-system

Source: https://github.com/strapi/design-system/blob/main/docs/stories/04-components/Flex.mdx

Import the Flex component from the Strapi Design System package. This is the standard import used in all examples.

```javascript
import { Flex } from '@strapi/design-system';
```

--------------------------------

### setOpacity usage example

Source: https://github.com/strapi/design-system/blob/main/docs/stories/05-utilities/Helpers.mdx

Example of using setOpacity in a styled-component to apply 20% opacity to a theme color.

```tsx
import { setOpacity } from '@strapi/design-system';

// In a styled-component or CSS-in-JS
const Overlay = styled.div`
  background: ${({ theme }) => setOpacity(theme.colors.neutral800, 0.2)};
`;
```

--------------------------------

### extractStyleFromTheme usage example

Source: https://github.com/strapi/design-system/blob/main/docs/stories/05-utilities/Helpers.mdx

Example of using extractStyleFromTheme to get theme tokens for background, padding, and border-radius in a styled-component.

```tsx
import { extractStyleFromTheme } from '@strapi/design-system';

const Badge = styled.span`
  background: ${({ theme }) =>
    extractStyleFromTheme(theme.colors, 'primary600', theme.colors.primary600)};
  padding: ${({ theme }) =>
    extractStyleFromTheme(theme.spaces, 1, '4px')};
  border-radius: ${({ theme }) =>
    extractStyleFromTheme(theme.borderRadius, 1, '4px')};
`;
```

--------------------------------

### Import DismissibleLayer from @strapi/design-system

Source: https://github.com/strapi/design-system/blob/main/docs/stories/05-utilities/DismissibleLayer.mdx

Import the DismissibleLayer component from the design system package. This is the only code example shown on the page.

```javascript
import { DismissibleLayer } from '@strapi/design-system';
```

--------------------------------

### handleResponsiveValues usage example

Source: https://github.com/strapi/design-system/blob/main/docs/stories/05-utilities/Helpers.mdx

Example of using handleResponsiveValues in a styled-component to generate responsive padding and margin.

```tsx
import { handleResponsiveValues } from '@strapi/design-system';
import styled from 'styled-components';

const Card = styled.div`
  ${({ theme }) =>
    handleResponsiveValues(
      {
        padding: { initial: 2, medium: 4, large: 6 },
        marginBottom: 4,
      },
      theme,
    )}
`;
```

--------------------------------

### Figma SVG export example

Source: https://github.com/strapi/design-system/blob/main/docs/stories/01-foundations/icons/overview.mdx

Example of an SVG exported from Figma. Contains width, height, fill="none", and fill="black" attributes that need to be removed for use in the library.

```xml
<svg width="32" height="32" viewBox="0 0 32 32" fill="none" xmlns="http://www.w3.org/2000/svg">
    <path d="M26.7075 12.7075L16.7075 22.7075C16.6146 22.8005 16.5043 22.8742 16.3829 22.9246C16.2615 22.9749 16.1314 23.0008 16 23.0008C15.8686 23.0008 15.7385 22.9749 15.6171 22.9246C15.4957 22.8742 15.3854 22.8005 15.2925 22.7075L5.29249 12.7075C5.15248 12.5676 5.05712 12.3894 5.01846 12.1953C4.97981 12.0012 4.99962 11.8 5.07537 11.6172C5.15112 11.4344 5.27942 11.2782 5.44401 11.1683C5.60861 11.0584 5.8021 10.9998 5.99999 11H26C26.1979 10.9998 26.3914 11.0584 26.556 11.1683C26.7206 11.2782 26.8489 11.4344 26.9246 11.6172C27.0004 11.8 27.0202 12.0012 26.9815 12.1953C26.9429 12.3894 26.8475 12.5676 26.7075 12.7075Z" fill="black"/>
</svg>
```

--------------------------------

### customizeContent function for MultiSelect

Source: https://github.com/strapi/design-system/blob/main/docs/stories/03-inputs/Select.mdx

Example of a customizeContent function that returns a string based on the selected values.

```javascript
const customizeContent = (values: string[]) => `${values.length} are currently selected`;
```

--------------------------------

### Hide focus outlines when using mouse with what-input

Source: https://github.com/strapi/design-system/blob/main/docs/stories/00-getting started/Troubleshooting.mdx

Add this CSS to your global styles to hide focus outlines when using a mouse, while keeping them for keyboard users. Requires installing and importing the what-input library.

```css
[data-whatintent='mouse'] *:focus {
  outline: none;
}
```

--------------------------------

### SVG icon before optimization

Source: https://github.com/strapi/design-system/blob/main/docs/stories/01-foundations/icons/overview.mdx

The original SVG icon with explicit width, height, fill, and clip-path attributes. This is the starting point before applying the optimization steps.

```xml
<svg width="32" height="32" viewBox="0 0 32 32" fill="none" xmlns="http://www.w3.org/2000/svg">
    <g clip-path="url(#clip0_1_2322)">
        <path d="M31.3162 25.746L28.3162 26.746C28.088 26.8224 27.8398 26.8139 27.6173 26.7221C27.3948 26.6302 27.2129 26.4612 27.105 26.246L23.3812 18.7973H13C12.7348 18.7973 12.4804 18.6919 12.2929 18.5044C12.1053 18.3169 12 18.0625 12 17.7973V14.0898C10.3892 14.5706 9.00529 15.6151 8.10114 17.0322C7.19698 18.4494 6.83299 20.1445 7.07569 21.8079C7.31838 23.4713 8.15156 24.9918 9.42294 26.0915C10.6943 27.1912 12.319 27.7967 14 27.7973C17.2387 27.7973 20.2612 25.541 21.0312 22.5473C21.0641 22.4201 21.1216 22.3006 21.2006 22.1956C21.2797 22.0906 21.3786 22.0022 21.4918 21.9355C21.6049 21.8688 21.7301 21.825 21.8602 21.8066C21.9903 21.7883 22.1228 21.7957 22.25 21.8285C22.3772 21.8614 22.4967 21.9189 22.6017 21.9979C22.7067 22.077 22.795 22.1759 22.8618 22.2891C22.9285 22.4022 22.9723 22.5274 22.9907 22.6575C23.009 22.7876 23.0016 22.9201 22.9687 23.0473C21.9612 26.9598 18.19 29.7973 14 29.7973C11.7882 29.796 9.65436 28.9803 8.00571 27.5059C6.35706 26.0314 5.30906 24.0016 5.06174 21.8037C4.81442 19.6058 5.3851 17.3937 6.66485 15.5898C7.94461 13.7859 9.84381 12.5163 12 12.0235V9.64854C11.1943 9.40833 10.502 8.88616 10.0497 8.1775C9.5974 7.46884 9.41528 6.62104 9.53665 5.78914C9.65803 4.95724 10.0748 4.19682 10.7107 3.64693C11.3467 3.09704 12.1593 2.79443 13 2.79443C13.8407 2.79443 14.6533 3.09704 15.2893 3.64693C15.9252 4.19682 16.3419 4.95724 16.4633 5.78914C16.5847 6.62104 16.4026 7.46884 15.9503 8.1775C15.4979 8.88616 14.8057 9.40833 14 9.64854V11.7973H21C21.2652 11.7973 21.5196 11.9026 21.7071 12.0902C21.8946 12.2777 22 12.5321 22 12.7973C22 13.0625 21.8946 13.3169 21.7071 13.5044C21.5196 13.6919 21.2652 13.7973 21 13.7973H14V16.7973H24C24.1856 16.7974 24.3674 16.8491 24.5253 16.9467C24.6831 17.0443 24.8107 17.1838 24.8937 17.3498L28.5062 24.5748L30.6837 23.8485C30.9354 23.7647 31.21 23.7842 31.4472 23.9028C31.6845 24.0214 31.8649 24.2294 31.9487 24.481C32.0326 24.7327 32.0131 25.0073 31.8945 25.2445C31.7759 25.4818 31.5679 25.6622 31.3162 25.746Z" fill="black"/>
    </g>
    <defs>
        <clipPath id="clip0_1_2322">
            <rect width="32" height="32" fill="white" transform="translate(0 0.797363)"/>
        </clipPath>
    </defs>
</svg>
```

--------------------------------

### Usage of AccessibleIcon with a close button

Source: https://github.com/strapi/design-system/blob/main/docs/stories/05-utilities/AccessibleIcon.mdx

Wrap an icon with AccessibleIcon and provide a label prop to make it accessible. This example shows a close button that uses the Cross icon with the label 'Close'.

```tsx
import { AccessibleIcon } from '@strapi/design-system';
import { Cross } from '@strapi/icons';

const CloseButton = ({ onClose }) => {
  return (
    <button onClick={onClose}>
      <AccessibleIcon label="Close">
        <Cross />
      </AccessibleIcon>
    </button>
  );
};
```

--------------------------------

### Enter pre-release mode with yarn prerelease:enter

Source: https://github.com/strapi/design-system/blob/main/CONTRIBUTING.md

Sets up changesets for pre-releases. Replace <tag> with a tag like 'beta'. If already in pre-release mode, you'll see an error.

```shell
yarn prerelease:enter <tag>
```

--------------------------------

### Clone the repository

Source: https://github.com/strapi/design-system/blob/main/CONTRIBUTING.md

Clone your forked repository and navigate into the project directory.

```bash
git clone git@github.com:YOUR_USERNAME/design-system.git
cd design-system
```

--------------------------------

### Import SimpleMenu and MenuItem

Source: https://github.com/strapi/design-system/blob/main/docs/stories/04-components/SimpleMenu.mdx

Import the SimpleMenu and MenuItem components from the design system.

```js
import { SimpleMenu, MenuItem } from '@strapi/design-system';
```

--------------------------------

### Import EmptyStateLayout from @strapi/design-system

Source: https://github.com/strapi/design-system/blob/main/docs/stories/04-components/EmptyStateLayout.mdx

Import the EmptyStateLayout component from the design system package.

```javascript
import { EmptyStateLayout } from '@strapi/design-system';
```

--------------------------------

### Import Portal from @strapi/design-system

Source: https://github.com/strapi/design-system/blob/main/docs/stories/05-utilities/Portal.mdx

Import the Portal component from the design system package.

```javascript
import { Portal } from '@strapi/design-system';
```

--------------------------------

### Import and use a symbol

Source: https://github.com/strapi/design-system/blob/main/docs/stories/01-foundations/icons/Symbols.mdx

Import a symbol from '@strapi/icons/symbol' and render it with a width prop. Only width and height should be set; colors are preset.

```tsx
import { SYMBOL_NAME } from '@strapi/icons/symbol';

const MyComponent = () => {
  return <SYMBOL_NAME width="14rem" />;
};
```

--------------------------------

### Import Searchbar and SearchForm

Source: https://github.com/strapi/design-system/blob/main/docs/stories/04-components/Searchbar.mdx

Import the Searchbar and SearchForm components from the @strapi/design-system package.

```js
import { Searchbar, SearchForm } from '@strapi/design-system';
```

--------------------------------

### Import and use an icon

Source: https://github.com/strapi/design-system/blob/main/docs/stories/01-foundations/icons/Icons.mdx

Import an icon from '@strapi/icons' and render it with a fill prop. The fill prop accepts theme colors or regular string values.

```tsx
import { ICON_NAME } from '@strapi/icons';

const MyComponent = () => {
  return <ICON_NAME fill="primary700" />;
};
```

--------------------------------

### Provider with locale and theme

Source: https://github.com/strapi/design-system/blob/main/docs/stories/05-utilities/DesignSystemProvider.mdx

Wrap your app with DesignSystemProvider, passing optional locale and theme props. Defaults are 'en-GB' and lightTheme respectively.

```tsx
import { DesignSystemProvider, lightTheme } from '@strapi/design-system';

const MyApp = () => (
  <DesignSystemProvider locale="en-GB" theme={lightTheme}>
    <App />
  </DesignSystemProvider>
);
```

--------------------------------

### Wrap app with DesignSystemProvider

Source: https://github.com/strapi/design-system/blob/main/docs/stories/00-getting started/welcome.mdx

Wrap your application with the DesignSystemProvider to use the Strapi Design System. You can optionally pass a theme and locale, but defaults are provided if omitted.

```jsx
import { DesignSystemProvider, lightTheme } from '@strapi/design-system';

function MyApp({ children }) {
  return (
    <DesignSystemProvider locale="en-GB" theme={lightTheme}>
      {children}
    </DesignSystemProvider>
  );
}

export default App;
```

--------------------------------

### Import Card components

Source: https://github.com/strapi/design-system/blob/main/docs/stories/04-components/Card.mdx

Import all Card subcomponents from '@strapi/design-system'.

```javascript
import {
  Card,
  CardHeader,
  CardBody,
  CardCheckbox,
  CardAction,
  CardAsset,
  CardTimer,
  CardContent,
  CardBadge,
  CardTitle,
  CardSubtitle,
} from '@strapi/design-system';
```

--------------------------------

### Import Grid from @strapi/design-system

Source: https://github.com/strapi/design-system/blob/main/docs/stories/04-components/Grid.mdx

Import the Grid component from the Strapi Design System package.

```javascript
import { Grid } from '@strapi/design-system';
```

--------------------------------

### Import Select components

Source: https://github.com/strapi/design-system/blob/main/docs/stories/03-inputs/Select.mdx

Import the Select components from the design system package.

```javascript
import {
  SingleSelect,
  SingleSelectOption,
  MultiSelect,
  MultiSelectOption,
  MultiSelectNested,
} from '@strapi/design-system';
```

--------------------------------

### Import Switch component

Source: https://github.com/strapi/design-system/blob/main/docs/stories/04-components/Switch.mdx

Import the Switch component from the @strapi/design-system package.

```javascript
import { Switch } from '@strapi/design-system';
```

--------------------------------

### Import utilities from @strapi/design-system

Source: https://github.com/strapi/design-system/blob/main/docs/stories/05-utilities/Helpers.mdx

Import the utility functions and types from the design system package.

```tsx
import {
  setOpacity,
  handleResponsiveValues,
  KeyboardKeys,
  extractStyleFromTheme,
  type ResponsiveProps,
  type Breakpoint,
} from '@strapi/design-system';
```

--------------------------------

### Import DesignSystemProvider

Source: https://github.com/strapi/design-system/blob/main/docs/stories/05-utilities/DesignSystemProvider.mdx

Import the DesignSystemProvider component from the @strapi/design-system package.

```tsx
import { DesignSystemProvider } from '@strapi/design-system';
```

--------------------------------

### Replace ThemeProvider with DesignSystemProvider

Source: https://github.com/strapi/design-system/blob/main/docs/stories/00-getting started/migration guides/migration-v1-v2.mdx

ThemeProvider has been removed and replaced with DesignSystemProvider. Update your imports accordingly.

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

--------------------------------

### Import JSONInput

Source: https://github.com/strapi/design-system/blob/main/docs/stories/03-inputs/JSONInput.mdx

Import the JSONInput component from the @strapi/design-system package.

```javascript
import { JSONInput } from '@strapi/design-system';
```

--------------------------------

### Import Pagination components

Source: https://github.com/strapi/design-system/blob/main/docs/stories/04-components/Pagination.mdx

Import the Pagination component and its subcomponents from the Strapi design system.

```js
import { Dots, NextLink, PageLink, Pagination, PreviousLink } from '@strapi/design-system';
```

--------------------------------

### Import Tooltip component

Source: https://github.com/strapi/design-system/blob/main/docs/stories/04-components/Tooltip.mdx

Import the Tooltip component from the @strapi/design-system package. This is the first step to using the component in your project.

```js
import { Tooltip } from '@strapi/design-system';
```

--------------------------------

### Import Toggle component

Source: https://github.com/strapi/design-system/blob/main/docs/stories/03-inputs/Toggle.mdx

Import the Toggle component from the @strapi/design-system package.

```js
import { Toggle } from '@strapi/design-system';
```

--------------------------------

### Import Popover from @strapi/design-system

Source: https://github.com/strapi/design-system/blob/main/docs/stories/04-components/Popover.mdx

Import the Popover component from the design system package.

```js
import { Popover } from '@strapi/design-system';
```

--------------------------------

### Import Select from @strapi/ui-primitives

Source: https://github.com/strapi/design-system/blob/main/docs/stories/02-primitives/Select.mdx

Import the Select component from the @strapi/ui-primitives package.

```ts
import { Select } from '@strapi/ui-primitives';
```

--------------------------------

### Import Alert component

Source: https://github.com/strapi/design-system/blob/main/docs/stories/04-components/Alert.mdx

Import the Alert component from the @strapi/design-system package.

```js
import { Alert } from '@strapi/design-system';
```

--------------------------------

### Import TimePicker

Source: https://github.com/strapi/design-system/blob/main/docs/stories/03-inputs/TimePicker.mdx

Import the TimePicker component from the design system.

```js
import { TimePicker } from '@strapi/design-system';
```

--------------------------------

### Import FocusTrap from @strapi/design-system

Source: https://github.com/strapi/design-system/blob/main/docs/stories/05-utilities/FocusTrap.mdx

Import the FocusTrap component from the Strapi design system package.

```javascript
import FocusTrap from '@strapi/design-system';
```

--------------------------------

### DesignSystemProvider

Source: https://github.com/strapi/design-system/blob/main/docs/stories/05-utilities/DesignSystemProvider.mdx

The root provider component for the Design System. It accepts optional locale and theme props, defaulting to 'en-GB' and lightTheme respectively.

```APIDOC
## DesignSystemProvider

### Description
The root provider for your Design System components. An abstraction around styled-component's ThemeProvider that also includes GlobalStyles as well as an unique provider supplying values to components.

### Usage
```tsx
import { DesignSystemProvider, lightTheme } from '@strapi/design-system';

const MyApp = () => (
  <DesignSystemProvider locale="en-GB" theme={lightTheme}>
    <App />
  </DesignSystemProvider>
);
```

### Props
- **locale** (string) - Optional - The locale for the provider. Defaults to 'en-GB'.
- **theme** (object) - Optional - The theme object. Defaults to lightTheme.

### Accessing the Context
```tsx
import { useDesignSystem } from '@strapi/design-system';

const MyLocale = () => {
  const { locale } = useDesignSystem();

  return <p>{locale}</p>;
};
```
```

--------------------------------

### Import Accordion from @strapi/design-system

Source: https://github.com/strapi/design-system/blob/main/docs/stories/04-components/Accordion.mdx

Import the Accordion component from the @strapi/design-system package to use it in your project.

```js
import { Accordion } from '@strapi/design-system';
```

--------------------------------

### Error when already in pre-release mode

Source: https://github.com/strapi/design-system/blob/main/CONTRIBUTING.md

This error appears when trying to enter pre-release mode while already in it. It is safe to continue.

```shell
`changeset pre enter` cannot be run when in pre mode
```

--------------------------------

### Import DateTimePicker

Source: https://github.com/strapi/design-system/blob/main/docs/stories/03-inputs/DateTimePicker.mdx

Import the DateTimePicker component from the design system package.

```js
import { DateTimePicker } from '@strapi/design-system/DateTimePicker';
```

--------------------------------

### Import Badge from @strapi/design-system

Source: https://github.com/strapi/design-system/blob/main/docs/stories/04-components/Badge.mdx

Import the Badge component from the Strapi design system package.

```js
import { Badge } from '@strapi/design-system';
```

--------------------------------

### Import Combobox

Source: https://github.com/strapi/design-system/blob/main/docs/stories/02-primitives/Combobox.mdx

Import the Combobox component from the @strapi/ui-primitives package.

```ts
import { Combobox } from '@strapi/ui-primitives';
```

--------------------------------

### Migrate Grid to composite component

Source: https://github.com/strapi/design-system/blob/main/docs/stories/00-getting started/migration guides/migration-v1-v2.mdx

Grid is now a composite component; GridItem has been removed. Use Grid.Root and Grid.Item instead.

```diff
- 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>
```

--------------------------------

### Import LinkButton

Source: https://github.com/strapi/design-system/blob/main/docs/stories/04-components/LinkButton.mdx

Import the LinkButton component from the @strapi/design-system package.

```js
import { LinkButton } from '@strapi/design-system';
```

--------------------------------

### Import Breadcrumbs components

Source: https://github.com/strapi/design-system/blob/main/docs/stories/04-components/Breadcrumbs.mdx

Import the necessary components from the @strapi/design-system package.

```js
import { Breadcrumbs, Crumb, CrumbLink, CrumbSimpleMenu, MenuItem } from '@strapi/design-system';
```

--------------------------------

### Import Modal from @strapi/design-system

Source: https://github.com/strapi/design-system/blob/main/docs/stories/04-components/Modal.mdx

Import the Modal component from the design system package for use in your application.

```javascript
import { Modal } from '@strapi/design-system';
```

--------------------------------

### Import Dialog from @strapi/design-system

Source: https://github.com/strapi/design-system/blob/main/docs/stories/04-components/Dialog.mdx

Import the Dialog component from the Strapi design system package.

```js
import { Dialog } from '@strapi/design-system';
```

--------------------------------

### Responsive object with breakpoint keys

Source: https://github.com/strapi/design-system/blob/main/docs/stories/01-foundations/responsive.mdx

Use an object with breakpoint keys to specify different values for each breakpoint.

```tsx
<Box padding={{ initial: 2, medium: 4, large: 6 }} />
```

--------------------------------

### Import Typography

Source: https://github.com/strapi/design-system/blob/main/docs/stories/01-foundations/typography.mdx

Import the Typography component from the Strapi Design System.

```jsx
import { Typography } from '@strapi/design-system';
```

--------------------------------

### Import BaseLink

Source: https://github.com/strapi/design-system/blob/main/docs/stories/02-primitives/BaseLink.mdx

Import the BaseLink component from the @strapi/design-system package.

```javascript
import { BaseLink } from '@strapi/design-system';
```

--------------------------------

### Import NumberInput

Source: https://github.com/strapi/design-system/blob/main/docs/stories/03-inputs/NumberInput.mdx

Import the NumberInput component from the Strapi design system.

```js
import { NumberInput } from '@strapi/design-system';
```

--------------------------------

### Import Combobox and ComboboxOption

Source: https://github.com/strapi/design-system/blob/main/docs/stories/03-inputs/Combobox.mdx

Import the Combobox and ComboboxOption components from the design system package.

```js
import { Combobox, ComboboxOption } from '@strapi/design-system';
```

--------------------------------

### Import DatePicker

Source: https://github.com/strapi/design-system/blob/main/docs/stories/03-inputs/DatePicker.mdx

Import the DatePicker component from the design system package.

```javascript
import { DatePicker } from '@strapi/design-system';
```

--------------------------------

### Import TextInput

Source: https://github.com/strapi/design-system/blob/main/docs/stories/03-inputs/TextInput.mdx

Import the TextInput component from the design system package.

```javascript
import { TextInput } from '@strapi/design-system';
```

--------------------------------

### Import RawTable components

Source: https://github.com/strapi/design-system/blob/main/docs/stories/04-components/RawTable.mdx

Import the RawTable and its subcomponents from @strapi/design-system. This is the required import for using the table components.

```js
import { RawTable, RawTh, RawTd, RawTr, RawThead, RawTbody } from '@strapi/design-system';
```

--------------------------------

### Import Tabs from @strapi/design-system

Source: https://github.com/strapi/design-system/blob/main/docs/stories/04-components/Tabs.mdx

Import the Tabs component from the Strapi design system package.

```javascript
import { Tabs } from '@strapi/design-system';
```

--------------------------------

### Import Textarea from @strapi/design-system

Source: https://github.com/strapi/design-system/blob/main/docs/stories/03-inputs/Textarea.mdx

Import the Textarea component from the Strapi design system package.

```javascript
import { Textarea } from '@strapi/design-system';
```

--------------------------------

### Import ProgressBar from @strapi/design-system

Source: https://github.com/strapi/design-system/blob/main/docs/stories/04-components/ProgressBar.mdx

Import the ProgressBar component from the @strapi/design-system package. This is the first step to using the component in your application.

```js
import { ProgressBar } from '@strapi/design-system';
```

--------------------------------

### Import LiveRegions from @strapi/design-system

Source: https://github.com/strapi/design-system/blob/main/docs/stories/04-components/LiveRegions.mdx

Import the LiveRegions component from the Strapi Design System package.

```js
import { LiveRegions } from '@strapi/design-system';
```

--------------------------------

### Import Avatar component

Source: https://github.com/strapi/design-system/blob/main/docs/stories/04-components/Avatar.mdx

Import the Avatar component from the @strapi/design-system package to use it in your project.

```js
import { Avatar } from '@strapi/design-system';
```

--------------------------------

### Import Button component

Source: https://github.com/strapi/design-system/blob/main/docs/stories/04-components/Button.mdx

Import the Button component from the @strapi/design-system package to use it in your application.

```javascript
import { Button } from '@strapi/design-system';
```

--------------------------------

### Responsive array mapping to breakpoints

Source: https://github.com/strapi/design-system/blob/main/docs/stories/01-foundations/responsive.mdx

Use an array to map values to breakpoints in order: initial, small, medium, large.

```tsx
<Box padding={[2, 4, 6]} />
```

--------------------------------

### handleResponsiveValues

Source: https://github.com/strapi/design-system/blob/main/docs/stories/05-utilities/Helpers.mdx

Takes an object of responsive props (spacing, layout, typography, etc.) and the theme, and returns a string of CSS (including media queries) that you can inject into styled-components or any CSS-in-JS solution. Supports breakpoints: `initial`, `small`, `medium`, `large`.

```APIDOC
## handleResponsiveValues

### Description
Takes an object of responsive props (spacing, layout, typography, etc.) and the theme, and returns a string of CSS (including media queries) that you can inject into styled-components or any CSS-in-JS solution. Supports breakpoints: `initial`, `small`, `medium`, `large`.

### Signature
```ts
handleResponsiveValues(values: ResponsiveProps, theme: DefaultTheme): string
```

### Parameters
- **values** (ResponsiveProps) – Object of CSS-related props; values can be theme tokens or responsive objects (e.g. initial: 2, large: 4)
- **theme** (DefaultTheme) – Strapi theme (e.g. from `useTheme()` or `props.theme` in styled-components)

### Responsive value shape
A property can be a single value (used as the initial value) or an object keyed by breakpoint:

```ts
// Single value
padding: 2

// Responsive object
padding: { initial: 1, medium: 2, large: 4 }
```

### Exported types
- **ResponsiveProps** – Props object accepted by `handleResponsiveValues` (spacing, layout, typography, etc.)
- **Breakpoint** – `'initial' | 'small' | 'medium' | 'large'`
- **ResponsiveProperty<T>** – A value or object keyed by breakpoint
- **ResponsiveThemeProperty** – Theme-aware responsive property type

### Example
```tsx
import { handleResponsiveValues } from '@strapi/design-system';
import styled from 'styled-components';

const Card = styled.div`
  ${({ theme }) =>
    handleResponsiveValues(
      {
        padding: { initial: 2, medium: 4, large: 6 },
        marginBottom: 4,
      },
      theme,
    )}
`;
```
```

--------------------------------

### Import Checkbox component

Source: https://github.com/strapi/design-system/blob/main/docs/stories/03-inputs/Checkbox.mdx

Import the Checkbox component from the @strapi/design-system package.

```javascript
import { Checkbox } from '@strapi/design-system';
```

--------------------------------

### Import Field and useField

Source: https://github.com/strapi/design-system/blob/main/docs/stories/04-components/Field.mdx

Import the Field component and useField hook from the design system.

```js
import { Field, useField } from '@strapi/design-system';
```

--------------------------------

### Import Box component

Source: https://github.com/strapi/design-system/blob/main/docs/stories/04-components/Box.mdx

Import the Box component from the Strapi design system package.

```js
import { Box } from '@strapi/design-system';
```

--------------------------------

### Use Icon component with color prop

Source: https://github.com/strapi/design-system/blob/main/docs/stories/00-getting started/migration guides/migration-v1-v2.mdx

Shows the diff for using the Icon component with the color prop instead of applying fill directly to the icon.

```diff
+ <Icon as={Plus} color="primary700" />
- <Plus fill="primary700" />
```

--------------------------------

### Import Radio component

Source: https://github.com/strapi/design-system/blob/main/docs/stories/03-inputs/Radio.mdx

Import the Radio component from the design system package.

```javascript
import { Radio } from '@strapi/design-system';
```

--------------------------------

### Select Anatomy Composition

Source: https://github.com/strapi/design-system/blob/main/docs/stories/02-primitives/Select.mdx

Shows the recommended composition of Select subcomponents: Root, Trigger, Value, Icon, Portal, Content, Viewport, Item, ItemText, ItemIndicator, NoValueFound, and CreateItem.

```tsx
<Select.Root>
  <Select.Trigger>
    <Select.Value placeholder="Pick me" />
    <Select.Icon />
  </Select.Trigger>
  <Select.Portal>
    <Select.Content>
      <Select.Viewport>
        <Select.Item value="1">
          <Select.ItemText>Option 1</Select.ItemText>
          <Select.ItemIndicator>
            <Check />
          </Select.ItemIndicator>
        </Select.Item>
        <Select.NoValueFound>No value found</Select.NoValueFound>
        <Select.CreateItem>Create a new value</Select.CreateItem>
      </Select.Viewport>
    </Select.Content>
  </Select.Portal>
</Select.Root>
```

--------------------------------

### Basic Combobox usage with @strapi/ui-primitives

Source: https://github.com/strapi/design-system/blob/main/packages/primitives/README.md

Shows a minimal Combobox component using the Root, Trigger, TextInput, Icon, Portal, Content, Viewport, Item, ItemText, ItemIndicator, NoValueFound, and CreateItem subcomponents. The Check icon is referenced but not defined in the snippet.

```jsx
import { Combobox } from '@strapi/ui-primitives';

() => {
  return (
    <Combobox.Root>
      <Combobox.Trigger>
        <Combobox.TextInput placeholder="Pick me" />
        <Combobox.Icon />
      </Combobox.Trigger>
      <Combobox.Portal>
        <Combobox.Content>
          <Combobox.Viewport>
            <Combobox.Item value="1">
              <Combobox.ItemText>Option 1</Combobox.ItemText>
              <Combobox.ItemIndicator>
                <Check />
              </Combobox.ItemIndicator>
            </Combobox.Item>
            <Combobox.NoValueFound>No value found</Combobox.NoValueFound>
            <Combobox.CreateItem>Create a new value</Combobox.CreateItem>
          </Combobox.Viewport>
        </Combobox.Content>
      </Combobox.Portal>
    </Combobox.Root>
  );
};
```

--------------------------------

### Remove direct imports from @strapi/design-system

Source: https://github.com/strapi/design-system/blob/main/docs/stories/00-getting started/migration guides/migration-v1-v2.mdx

Shows the diff for changing imports from subpaths to the root of the design-system package.

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

--------------------------------

### Import IconButton and IconButtonGroup

Source: https://github.com/strapi/design-system/blob/main/docs/stories/04-components/IconButton.mdx

Import the IconButton and IconButtonGroup components from the design system package.

```javascript
import { IconButton, IconButtonGroup } from '@strapi/design-system';
```

--------------------------------

### Import Divider component

Source: https://github.com/strapi/design-system/blob/main/docs/stories/04-components/Divider.mdx

Import the Divider component from the Strapi design system package.

```js
import { Divider } from '@strapi/design-system';
```

--------------------------------

### Import CarouselInput components

Source: https://github.com/strapi/design-system/blob/main/docs/stories/04-components/Carousel.mdx

Import the CarouselInput component and its related components (CarouselSlide, CarouselImage, CarouselActions) from the @strapi/design-system package.

```js
import { CarouselInput, CarouselSlide, CarouselImage, CarouselActions } from '@strapi/design-system';
```

--------------------------------

### Basic Select usage with @strapi/ui-primitives

Source: https://github.com/strapi/design-system/blob/main/packages/primitives/README.md

Shows a minimal Select component using the Root, Trigger, Value, Icon, Portal, Content, Viewport, Item, ItemText, and ItemIndicator subcomponents. The Check icon is referenced but not defined in the snippet.

```jsx
import { Select } from '@strapi/ui-primitives';

() => {
  return (
    <Select.Root>
      <Select.Trigger>
        <Select.Value placeholder="Pick me" />
        <Select.Icon />
      </Select.Trigger>
      <Select.Portal>
        <Select.Content>
          <Select.Viewport>
            <Select.Item value="1">
              <Select.ItemText>Option 1</Select.ItemText>
              <Select.ItemIndicator>
                <Check />
              </Select.ItemIndicator>
            </Select.Item>
          </Select.Viewport>
        </Select.Content>
      </Select.Portal>
    </Select.Root>
  );
};
```

--------------------------------

### Import Link component

Source: https://github.com/strapi/design-system/blob/main/docs/stories/04-components/Link.mdx

Import the Link component from the design system package.

```js
import { Link } from '@strapi/design-system';
```

--------------------------------

### Icon component template with forwardRef

Source: https://github.com/strapi/design-system/blob/main/docs/stories/01-foundations/icons/overview.mdx

Standard template for all icon components. Typed with SVGProps and supports forwarding refs via forwardRef. Uses a 32x32 viewBox and fill="currentColor".

```tsx
const CaretDown = (props: SVGProps<SVGSVGElement>, ref: Ref<SVGSVGElement>) => (
  <svg
    xmlns="http://www.w3.org/2000/svg"
    viewBox="0 0 32 32"
    width="1.6rem"
    height="1.6rem"
    fill="currentColor"
    ref={ref}
    {...props}
  >
    <path d="m26.708 12.708-10 10a1 1 0 0 1-1.415 0l-10-10A1 1 0 0 1 6 11h20a1 1 0 0 1 .707 1.707" />
  </svg>
);
const ForwardRef = forwardRef(CaretDown);
export default ForwardRef;
```

--------------------------------

### Select.Root

Source: https://github.com/strapi/design-system/blob/main/docs/stories/02-primitives/Select.mdx

The root component that manages the state and behavior of the select. It wraps all other select components.

```APIDOC
## Select.Root

### Description
The root component that manages the state and behavior of the select. It wraps all other select components.

### Usage
```tsx
<Select.Root>
  ...
</Select.Root>
```

### API Reference
Refer to the ArgTypes for Select.Root in the source documentation for detailed props.
```

--------------------------------

### Use Field API with SingleSelect

Source: https://github.com/strapi/design-system/blob/main/docs/stories/00-getting started/migration guides/migration-v1-v2.mdx

Shows the before and after usage of the Field API with SingleSelect, wrapping the input with Field.Root, Field.Label, Field.Error, and Field.Hint.

```tsx
// before
return <SingleSelect label={label} error={error} required={required} value={value} onChange={handleChange} />;

// after
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>
);
```

--------------------------------

### Select.Item

Source: https://github.com/strapi/design-system/blob/main/docs/stories/02-primitives/Select.mdx

An individual option that can be selected by the user.

```APIDOC
## Select.Item

### Description
An individual option that can be selected by the user.

### Usage
```tsx
<Select.Item value="1">
  ...
</Select.Item>
```

### API Reference
Refer to the ArgTypes for Select.Item in the source documentation for detailed props.
```

--------------------------------

### Import TextButton

Source: https://github.com/strapi/design-system/blob/main/docs/stories/04-components/TextButton.mdx

Import the TextButton component from the design system.

```ts
import { TextButton } from '@strapi/design-system';
```

--------------------------------

### Import Table components

Source: https://github.com/strapi/design-system/blob/main/docs/stories/04-components/Table.mdx

Import the Table and its subcomponents from the design system package.

```js
import { Table, Thead, Tbody, Tr, Td, Th } from '@strapi/design-system';
```

--------------------------------

### Import Loader

Source: https://github.com/strapi/design-system/blob/main/docs/stories/04-components/Loader.mdx

Import the Loader component from the design system.

```js
import { Loader } from '@strapi/design-system';
```

--------------------------------

### Update IconButton API: use label and children

Source: https://github.com/strapi/design-system/blob/main/docs/stories/00-getting started/migration guides/migration-v1-v2.mdx

The `icon` and `ariaLabel` props have been removed. Use `label` and `children` instead. Set `withTooltip` to `false` to disable the default tooltip.

```diff
- <IconButton icon={Plus} ariaLabel="Add" />
+ <IconButton withTooltip={false} label="Add"><Plus /></IconButton>
```

--------------------------------

### Select.Content

Source: https://github.com/strapi/design-system/blob/main/docs/stories/02-primitives/Select.mdx

The container that holds the select options and is displayed when the select is open.

```APIDOC
## Select.Content

### Description
The container that holds the select options and is displayed when the select is open.

### Usage
```tsx
<Select.Content>
  ...
</Select.Content>
```

### API Reference
Refer to the ArgTypes for Select.Content in the source documentation for detailed props.
```

--------------------------------

### Portal Component

Source: https://github.com/strapi/design-system/blob/main/docs/stories/05-utilities/Portal.mdx

A declarative wrapper around ReactDOM.createPortal that renders content outside the root React app. By default it mounts to document.body, but a custom container can be provided via the container prop.

```APIDOC
## Portal Component

### Description
A declarative wrapper around ReactDOM.createPortal that allows rendering content outside the root React app. By default, it mounts to `document.body`, but a custom container can be supplied via the `container` prop.

### Import
```js
import { Portal } from '@strapi/design-system';
```

### Props
- **container** (HTMLElement) - Optional - The DOM element to render the portal into. Defaults to `globalThis.document.body`.

### Usage Example
```jsx
<Portal container={customContainer}>
  {/* content to render outside the root app */}
</Portal>
```

### Notes
- The default container is `globalThis.document.body`.
- The `container` prop allows rendering into a specific element, useful for iframes or other custom contexts.
```

--------------------------------

### SimpleMenu with Links and Routing Libraries

Source: https://github.com/strapi/design-system/blob/main/docs/stories/04-components/SimpleMenu.mdx

Use the `tag` prop to integrate with routing libraries like react-router-dom or next/link. The `isLink` prop infers an internal link, while `isExternal` is for external links.

```jsx
import { SimpleMenu, MenuItem } from '@strapi/design-system';
import { NavLink } from 'react-router-dom'; // or import { Link } from 'next/link'

const MyMenu = () => {
  return (
    <SimpleMenu label="Navigation">
      <MenuItem as={NavLink} to="/" isLink>
        Home
      </MenuItem>
      <MenuItem as={NavLink} to="/accounts" isLink>
        Accounts
      </MenuItem>
      <MenuItem href="https://strapi.io/" isExternal>
        Billing Provider
      </MenuItem>
    </SimpleMenu>
  );
};
```

--------------------------------

### Import Status component

Source: https://github.com/strapi/design-system/blob/main/docs/stories/04-components/Status.mdx

Import the Status component from the Strapi Design System package.

```js
import { Status } from '@strapi/design-system';
```

--------------------------------

### Rename ToggleInput to Toggle

Source: https://github.com/strapi/design-system/blob/main/docs/stories/00-getting started/migration guides/migration-v1-v2.mdx

Shows the diff for renaming ToggleInput to Toggle in imports.

```diff
- import { ToggleInput } from '@strapi/design-system'
+ import { Toggle } from '@strapi/design-system'
```

--------------------------------

### Menu Basic Usage

Source: https://github.com/strapi/design-system/blob/main/docs/stories/04-components/SimpleMenu.mdx

Compose the Menu component collection with Root, Trigger, Content, Item, and Separator. The `onSelect` callback handles item selection, and the `disabled` prop disables an item.

```jsx
import { Menu } from '@strapi/design-system';

const MyMenu = () => {
  return (
    <Menu.Root>
      <Menu.Trigger>Actions</Menu.Trigger>
      <Menu.Content>
        <Menu.Item onSelect={() => console.log('opening')}>Open</MenuItem>
        <Menu.Separator />
        <Menu.Item disabled onSelect={() => console.log('cloning')}>
          Clone
        </Menu.Item>
        <Menu.Item onSelect={() => console.log('editing')}>Edit</MenuItem>
        <Menu.Item color="danger600" onSelect={() => console.log('delete')}>
          Delete
        </Menu.Item>
      </Menu.Content>
    </Menu.Root>
  );
};
```

--------------------------------

### Cleaned SVG for library use

Source: https://github.com/strapi/design-system/blob/main/docs/stories/01-foundations/icons/overview.mdx

The same SVG after removing width, height, fill="none", and path fill attributes. This is the format required for icons in the library.

```xml
<svg viewBox="0 0 32 32" xmlns="http://www.w3.org/2000/svg">
    <path d="M26.7075 12.7075L16.7075 22.7075C16.6146 22.8005 16.5043 22.8742 16.3829 22.9246C16.2615 22.9749 16.1314 23.0008 16 23.0008C15.8686 23.0008 15.7385 22.9749 15.6171 22.9246C15.4957 22.8742 15.3854 22.8005 15.2925 22.7075L5.29249 12.7075C5.15248 12.5676 5.05712 12.3894 5.01846 12.1953C4.97981 12.0012 4.99962 11.8 5.07537 11.6172C5.15112 11.4344 5.27942 11.2782 5.44401 11.1683C5.60861 11.0584 5.8021 10.9998 5.99999 11H26C26.1979 10.9998 26.3914 11.0584 26.556 11.1683C26.7206 11.2782 26.8489 11.4344 26.9246 11.6172C27.0004 11.8 27.0202 12.0012 26.9815 12.1953C26.9429 12.3894 26.8475 12.5676 26.7075 12.7075Z" />
</svg>
```

--------------------------------

### Add a changeset with yarn release:add

Source: https://github.com/strapi/design-system/blob/main/CONTRIBUTING.md

Activates an automated prompt to help create a changeset. Use this when adding a changeset for your pull request.

```shell
yarn release:add
```

--------------------------------

### Single value responsive prop

Source: https://github.com/strapi/design-system/blob/main/docs/stories/01-foundations/responsive.mdx

Use a single value to apply the same value to the initial breakpoint.

```tsx
<Box padding={2} />
```

--------------------------------

### Import Tag component

Source: https://github.com/strapi/design-system/blob/main/docs/stories/04-components/Tag.mdx

Import the Tag component from the design system package.

```js
import { Tag } from '@strapi/design-system';
```
Tokens:
Raw