DOCSEARCHbyAlgolia
Submit Docs

Strapi Design System

repository·main·Indexed 19 days ago

https://github.com/strapi/design-system

A set of guidelines and UI tools for building cohesive Strapi contributions and plugins. It includes the @strapi/ui-primitives library featuring accessible components like Combobox and Select, hooks such as useCallbackRef, useCollator, and useFilter, and a comprehensive migration guide from V1 to V2 covering API refactors, peer dependency updates, and icon mapping.

Tokens
45.2K
Snippets
187
Records
325
Agent score
66%

What's inside strapi-design-system

  1. Compose a Combobox component

    main

    The Combobox is a compound component. A standard implementation follows this structure:

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

    Sub-components:

    • Combobox.Root: The main wrapper.
    • Combobox.Trigger: The element that opens the list.
    • Combobox.TextInput: The input field for typing/filtering.
    • Combobox.Icon: An icon within the trigger.
    • Combobox.Portal: Renders the dropdown content in a portal.
    • Combobox.Content: The container for the dropdown list.
    • Combobox.Viewport: The scrollable area for items.
    • Combobox.Item: An individual selectable option.
    • Combobox.ItemText: The text label for an item.
    • Combobox.ItemIndicator: A visual indicator (like a checkmark) for the selected item.
    • Combobox.NoValueFound: Displayed when the filter matches no items.
    • Combobox.CreateItem: An option to trigger custom value creation.
    <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>

  2. Understand icon categories in the design system

    main

    Icons in the design system are categorized into two types based on how they should be used:

    • icons: These are intended to be customizable. You can apply styles like fill or stroke to them.
    • symbols: These are intended to be non-customizable. They typically have specific fill and stroke values applied directly to their internal path elements.

  3. Use NumberInput with different locales

    main

    The NumberInput component uses NumberFormatter and NumberParser to handle regional number formatting. This ensures that the displayed value and the user's input are consistent with local conventions.

    For example:

    • In en-US, 1000.5 is displayed as 1,000.5.
    • In fr-FR, 1000.5 is displayed as 1 000,5.

    When a user enters a value like 1.000,5 in a French locale, the NumberParser correctly identifies the comma as the decimal separator.

  4. Configure TimePicker size and steps

    main

    You can customize the visual size and the interval of time increments in the TimePicker:

    • Size: Use the size prop to set the component to either "S" (Small) or "M" (Medium). The default is "M".
    • Steps: Use the step prop to modify the pre-determined list of time options (e.g., changing the interval from the default 15 minutes).

  5. Tabs component sub-components

    main

    The Tabs component is structured into the following hierarchy:

    • Tabs.Root: The main container that manages state, variants, and error/disabled logic.
    • Tabs.List: The container for the tab triggers.
    • Tabs.Trigger: The interactive element used to switch between views. Requires a value prop.
    • Tabs.Content: The panel containing the view associated with a specific trigger. Requires a value prop matching the trigger.

  6. Configure Radio selection behavior

    main

    You can manage how radio items are selected using the following patterns:

    • Uncontrolled with initial value: Use the defaultValue prop on the Radio.Group to pre-select an item. If no defaultValue is provided, no item is selected by default.
    • Controlled: Manage the selection state manually by passing a value to the group and handling changes via an onChange handler.
    • Disabled state:
      • To disable the entire group, pass the disabled prop to Radio.Group.
      • To disable a specific option, pass the disabled prop to the individual Radio.Item.
    // Example: Setting an initial value
<Radio.Group defaultValue="option-1">
  <Radio.Item value="option-1" label="Option 1" />
  <Radio.Item value="option-2" label="Option 2" />
</Radio.Group>

  10. Configure Tabs variants and error states

    main

    The Tabs component supports several visual configurations:

    • Variants: Use the variant prop on Tabs.Root to switch between regular (default, with elevation) and simple (minimal).
    • Error States: Use the hasError prop on Tabs.Root. This must be a string corresponding to the value of the trigger you want to show an error on. In the simple variant, the error color takes precedence over the active tab color.

  12. Accessibility coding standards for assistive technologies

    main
    To support users relying on assistive technologies (such as screen readers or text-to-speech tools), the components follow specific coding standards regarding alternative text. When using components that involve assets, links, dropdowns, or call-to-actions, ensure you provide appropriate alternative text to convey the intended action or information.