Skip to main content

Storybook

Multi-Select

Allows users to select multiple options from a searchable dropdown list, displaying selections as removable tags. Use when a checkbox group would be too long or when options need to be searchable. Don't use when only one selection is allowed.

Figma Storybook Docs

Description

What it does

Lets users pick one or more options from a searchable dropdown list. Each chosen option appears as a removable tag inside the input field, giving users a clear summary of their selections without navigating away from the form.

Where it appears

Filter panels, form fields that assign categories or tags, bulk-action screens, and search refinement interfaces. Common examples include assigning stakeholder groups to a consultation, filtering engagement records by region or topic, and tagging community submissions.

Why it exists

A checkbox list becomes unwieldy when there are more than five or six options, or when the option set is dynamic. Multi-Select solves this by combining search and selection in a single compact control, reducing scroll and cognitive load for admin users working with large datasets.

Dependencies

Select, Checkbox, Input, Tag

Anatomy

PartRequired?Notes
Label Required Describes the field. Always visible above the input; never replaced by placeholder text alone.
Input trigger Required The clickable field that opens the dropdown and accepts typed search queries. Displays selected-value tags and the text cursor.
Selected-value tag Optional A removable tag rendered inside the input for each chosen option. Includes a close icon so the user can deselect without reopening the list.
Placeholder text Recommended Short hint shown inside an empty input (e.g. 'Search or select…'). Hidden once tags are present.
Dropdown panel Required Floating list of options that appears below (or above) the trigger when focused. Contains the search-filtered option items.
Search input (internal) Required The live-filter text field embedded in the trigger. Filters the option list as the user types.
Option item Required An individual selectable row in the dropdown. Shows a checkbox or tick indicator for selected state.
Select-all option Optional A top-of-list item that toggles all visible (filtered) options at once. Useful when bulk selection is a common workflow.
Empty state message Recommended Shown inside the dropdown when no options match the current search query (e.g. 'No results found').
Helper text Optional Supporting instruction or character/count guidance displayed below the input field.
Error message Optional Replaces helper text when validation fails. Paired with an error icon and --op-color-status-error styling.
Clear-all button Optional An action inside or adjacent to the input that removes all selected values at once. Provide when selections can grow large.
Chevron icon Recommended Rotates to indicate open/closed state of the dropdown panel.

Variants

Default

Standard multi-select with search filter

Use for most multi-selection scenarios where the option list has six or more items or the options are dynamic.

With select-all

Adds a 'Select all' toggle at the top of the dropdown

Use when selecting the full list (or a large portion of it) is a common user intent, such as assigning all regions to a consultation.

Grouped options

Options are organised under labelled group headings within the dropdown

Use when options naturally belong to categories (e.g. stakeholder types grouped by sector) to reduce visual scanning effort.

Fixed options (no search)

Dropdown shows all options with no filter input

Use only when the option set is small (five or fewer) and well-known, so search offers no real benefit.

Read-only

Selections are displayed as non-interactive tags; the input is not editable

Use in summary/review steps of a multi-step form, or in detail views where the field value is shown but cannot be changed in the current context.

States

State Behaviour
Default (empty) Input shows placeholder text and chevron. Dropdown is closed.
Focused (empty) Input receives a 3px focus ring using --op-color-interactive-focus. Dropdown opens showing the full unfiltered option list.
Typing / filtering Option list filters in real time as the user types. Non-matching options are hidden. If no options remain, the empty state message appears.
Option selected The chosen option gains a tick/checked indicator in the dropdown. A removable tag for the option appears inside the input field.
Multiple selections Tags stack left-to-right inside the input. The input field grows vertically if tags overflow a single line. The search text cursor remains at the end.
Tag removal Clicking the close icon on a tag deselects that option and removes the tag. The dropdown does not re-open automatically.
Dropdown open Chevron rotates 180°. Dropdown panel appears with --op-radius-md corners and a border using --op-color-border-default. Focus remains inside the composite control.
Disabled Input, tags, and chevron are rendered at reduced opacity. The field is not focusable. Existing selections are visible but cannot be changed.
Error Input border changes to --op-color-status-error. Error message replaces helper text below the input. The field retains full interactivity.
Loading A spinner appears inside the dropdown panel while options are being fetched asynchronously. Keyboard and pointer interactions are suspended until loading completes.

Usage guidelines

When to use

  • The user needs to assign multiple values from a predefined list, such as selecting stakeholder groups for a new consultation.
  • The option list has six or more items and would create excessive scroll or visual noise as a checkbox group.
  • Options are fetched dynamically or are too numerous to present at once (e.g. all suburbs in a state).
  • The user may want to search or type-ahead to find options quickly — for example, finding specific community topics from a long taxonomy.
  • Filtering records by multiple criteria simultaneously (e.g. filter engagement activity by region AND topic).

When not to use

  • Only one selection is allowed — use a Select or Radio group instead.
  • There are five or fewer options and they are all equally likely to be chosen — a Checkbox group is more scannable and requires fewer interactions.
  • The user needs to create new values not in the predefined list — use a tag input or combobox pattern with free-text creation instead.
  • The field is inside a narrow mobile form where the tag wrapping behaviour may cause layout issues — consider a full-screen selection sheet on small viewports.

Do / Don't

Do

Write the label as a clear noun phrase describing what is being selected, e.g. 'Stakeholder groups' or 'Consultation topics'.

Don't

Do not use the label as an instruction, e.g. 'Select one or more groups'. The component's affordance communicates multi-select.

Do

Provide an empty state message when search returns no results, e.g. 'No topics match your search'.

Don't

Do not leave the dropdown blank when filtering returns nothing — users will not know whether the list is loading or genuinely empty.

Do

Pre-populate selections when editing an existing record so users can see and adjust current values.

Don't

Do not silently clear existing selections when a form is re-opened or navigated back to.

Do

Limit tag labels to 30–40 characters max. Truncate with a tooltip if an option name is longer.

Don't

Do not let tag text wrap inside the tag — this breaks the visual rhythm of the input and can cause layout reflow.

Do

Use the 'Select all' variant when administrators routinely need to assign all options (e.g. grant access to all regions).

Don't

Do not show 'Select all' in filtered/search state if it would only select visible results — clarify the scope in the label.

Related: Select, Checkbox, Input, Tag

Was this page helpful?

Updated 9 September 2026