Searchable Multi Select

Anatomy

import {Field, SearchableMultiSelect} from '@staffbase/design';

<Field.Root>
  <Field.Label />
  <Field.Description />
  <SearchableMultiSelect.Root>
    <SearchableMultiSelect.Value>
      <SearchableMultiSelect.Chip />
      <SearchableMultiSelect.Input />
    </SearchableMultiSelect.Value>

    <SearchableMultiSelect.Popup>
      <SearchableMultiSelect.Empty />
      <SearchableMultiSelect.List>
        <SearchableMultiSelect.Group>
          <SearchableMultiSelect.GroupLabel />
          <SearchableMultiSelect.Collection>
            <SearchableMultiSelect.Item />
          </SearchableMultiSelect.Collection>
        </SearchableMultiSelect.Group>
      </SearchableMultiSelect.List>
    </SearchableMultiSelect.Popup>

  </SearchableMultiSelect.Root>
  <Field.Error />
</Field.Root>

API reference

Use the Field component to wrap SearchableMultiSelect and provide label, description, and error content.

All parts inherit their base behavior from Base UI Combobox. The sections below document all exports and highlight design-system additions.

Root

Creates the combobox context and state for filtering and multi-selection.

SearchableMultiSelect.Root always enables multi-select behavior (multiple={true}).

Value

Renders the value container, selected chips, clear button, and popup trigger.

Input

Text input used to filter available options.

Popup

Composed from Portal + Positioner + Popup in one part.

List

Container for options, groups, separators, and collection rendering.

Item

Selectable option row with built-in selected indicator.

Group

Groups related options together, typically with GroupLabel and Collection.

GroupLabel

Label for a grouped section of options.

Separator

Visual divider between list sections.

Chip

Represents a selected value and includes a built-in remove action.

Empty

Fallback content shown when no options match the current query.

Collection

Helper part for rendering nested collections (commonly used inside grouped lists).

Status

Optional live-region/status output for communicating result state to assistive technologies.

Examples

Grouped

With avatars

When to use

• Pick several options from a list that is long enough that typing is faster than scrolling.
• Show every selected value in the field as a removable chip, so the current selection stays visible without opening the list.
• Select from a large or remote dataset, such as users, channels, or tags, where options are fetched while the user types.
• Offer options that fall into named categories, such as Fruits and Vegetables, using grouped list sections.

When not to use

• Don’t use it when only one option can be selected from a searchable list — use Searchable Single Select instead.
• Don’t use it when only one option can be selected from a short, fixed list — use Select instead.
• Don’t use it to narrow down a list of results that is already shown on the page — use Filter instead.
• Don’t use it for five or fewer options that should all stay visible without interaction — use a group of Checkbox instead.
• Don’t use it when users need to enter values that are not in the list — use Text Field instead.
• Don’t use it to switch between two or three mutually exclusive views — use Segmented Control instead.

How to use

Structure

• Wrap the component in Field.Root and always give it a Field.Label.
• Put the chips and the SearchableMultiSelect.Input inside SearchableMultiSelect.Value so typing and the current selection share one field.
• Use Field.Description for guidance the user needs before selecting, and Field.Error for validation messages.
• Always provide SearchableMultiSelect.Empty content, so a query with no matches never leaves the popup blank.
• Set an explicit width on Field.Root; the field fills its container and the popup matches the field width.

Leading icon

• Add leadingIcon to SearchableMultiSelect.Value only when the icon says what kind of content is being selected, such as people, languages, or tags.
• Don’t add a leading icon for decoration — leave it out when it carries no meaning.
• Use at most one leading icon per field.

Placeholder

• Write a placeholder that hints at the kind of value expected, such as e.g. TypeScript, instead of repeating the label.
• Clear the placeholder as soon as one value is selected, so it never competes with the chips.
• Don’t put required rules, formats, or error text in the placeholder — use Field.Description or Field.Error instead.

Options list

• Group related options with SearchableMultiSelect.Group and label each group with SearchableMultiSelect.GroupLabel.
• Put a SearchableMultiSelect.Separator between groups so the sections stay visually distinct.
• The popup is capped at 272px tall and scrolls when the options exceed that height.
• Order already-selected options at the top of the list when the popup reopens, so the current selection is quick to review and undo.
• Show rich option rows, such as an avatar plus a secondary line, when the name alone doesn’t identify the option.
• Keep the chip label to the single value that identifies the option, such as the person’s name, even when the option row shows more detail.

Selected values

• Chips wrap onto multiple lines and the field grows in height as more values are selected.
• The input keeps a minimum width of 48px and moves to its own row once the chips leave less space than that, so the field can grow before the chips themselves wrap.
• Chips are capped at 200px wide and truncate longer labels with an ellipsis, so keep option labels short.
• A truncated chip has no tooltip on hover — the full value is only readable in the options list, so don’t rely on truncation to hide meaningful detail.
• Let users remove a single value with the remove button on its chip.
• The clear button next to the caret appears as soon as the field has a selection and removes all selected values at once.

Search behaviour

• Typing filters the list, and the caret icon is replaced by a search icon while the popup is open.
• Filter options on the client only when the full list is already loaded; otherwise fetch matches for the current query.
• Keep the typed query in the input when there are no matches, so the user can correct it instead of retyping.
• Clicking outside the popup, or the trigger again, closes the list and keeps the current selection.
• Selecting an option keeps the popup open, so several values can be picked in a row.

Validation

• Set invalid on Field.Root and render the message in Field.Error instead of styling the field yourself.
• Validate after the user leaves the field, not on every keystroke, so partial queries aren’t reported as errors.
• Mark a required field with requiredLabel on Field.Label.

Accessibility

• Always connect a Field.Label to the field — a placeholder is not a label.
• Keep the built-in accessible labels on the remove, clear, and open controls, or replace them with equally descriptive ones.
• Render SearchableMultiSelect.Status to announce result counts and loading state to screen reader users.
• Arrow keys move through the options, Enter toggles the highlighted option, and Escape closes the popup.
• Backspace in an empty input removes the last chip, so keyboard users can undo a selection without reaching for the mouse.
• Don’t rely on chip colour alone to signal that a value is selected — the chip label carries the meaning.

Content & UX copy

• Use Title Case for the field label, option labels, and group labels.
• Use sentence case and a full sentence ending in a period for Field.Description.
• Write the empty state as a short sentence naming what wasn’t found, such as No languages found.
• Keep option labels to a few words so they stay readable once they become chips.
• Use the same wording for an option in the list and in its chip.