Overview

Key Features

• List Type: Supports predefined lists with selectable items including checkboxes.
• Input Feedback: Supports input indicators, filled state, and autocomplete.
• Field Labels: Includes field label, description, and required indicators.
• Selection Display: Shows number of selected items using a badge.
• Customization with partials: Supports custom list creation with partials for list items, dividers and group titles.
• Accessibility: Fully keyboard and screen-reader accessible.

Anatomy

1. Field label (optional): Provides context for the input, guiding users on what to enter.
2. Input prompt : Gives users a hint about what to select or enter before any options are chosen. It expands to fill its container up to a maximum width of 480 px; for wider layouts, enable the fluid prop.
3. Description text (optional): Additional guidance or instructions related to the input, such as how to select multiple options.
4. Chevron icon button: Expands or collapses the multi-select list, allowing users to view and choose from available options.

1. Badge: Displays the number of selected items, providing a quick overview of the user’s choices.
2. Selected list items: Groups selected items at the top of the list for easy visibility and management.
3. List item checkbox: A control that allows users to select or deselect an item within the list.
4. List item label: Clearly identifies the option, ensuring users understand what they are selecting.
5. List item description (optional): Provides additional context or instructions to help users make informed selections.
6. Divider: Visually separates groups of items within the list, improving readability and organization.
7. Scrollbar: Enables navigation through long lists, allowing users to access additional options efficiently.

Look and Feel

States

States define how the component behaves and appears in different interactions:

• Default: The standard appearance when inactive
• Hover: Highlights the field when the user hovers over it
• Focus: Indicates active input with a visible focus indicator.
• Disabled: Prevents interaction and input, appearing visually subdued.
• Read-only: Displays content without allowing edits while maintaining a standard appearance.

Errors

Errors communicate invalid input through clear visual cues to help users correct mistakes. We use a red border around the input field, an error icon to indicate the issue, and an error message displayed below the field to provide further guidance.

Best Practice

Do:

• Use clear labels that describe what the user is selecting such as “Select your preferred topics”.
• Provide a brief but useful description text below the field to clarify how selections work “You can select up to 5 categories”
• Group related options logically using categories or sections to reduce cognitive load.

Don’t:

• Don’t create overly long or confusing option labels—keep them short and scannable. Avoid “A long descriptive option that is hard to read”
• Don’t display options in an illogical order—sort them alphabetically, by relevance, or in a structured hierarchy.

Links

The latest UI designs are in the Figma file, while the components are available in Storybook — a visual workspace where UI elements can be viewed and interacted with like a live demo, while being coded, tested, and documented in isolation. Supported stacks include Web Component, Blazor, Angular, React, and VueJS, linked below.

Feedback

Have feedback, an idea, or a bug to report? Head over to our Contributions page.