Searchable Single Select

Anatomy

import {SearchableSingleSelect} from '@staffbase/spark';

<SearchableSingleSelect.Root>
  <SearchableSingleSelect.Input />
  <SearchableSingleSelect.Popup>
    <SearchableSingleSelect.Empty />
    <SearchableSingleSelect.Status />
    <SearchableSingleSelect.List>
      <SearchableSingleSelect.Group>
        <SearchableSingleSelect.GroupLabel />
        <SearchableSingleSelect.Collection>
          <SearchableSingleSelect.Item />
        </SearchableSingleSelect.Collection>
      </SearchableSingleSelect.Group>
      <SearchableSingleSelect.Separator />
      <SearchableSingleSelect.Item />
    </SearchableSingleSelect.List>
  </SearchableSingleSelect.Popup>
</SearchableSingleSelect.Root>;

Examples

Grouped

API reference

Root

Manages the combobox’s open state, selected value, and available items.

Input

The text field that filters the list and displays the selected value.

Popup

Empty

Rendered inside the popup when no items match the current query.

List

Renders the list of items, or of groups when the options are grouped.

Item

Group

Wraps a labelled section of items inside the list.

GroupLabel

Collection

Renders an Item for each item within a Group.

Separator

Visually separates groups of items in the list.

Status

Announces result counts and loading state to assistive technology.

When to use

• Pick one option from a list that is long enough that typing is faster than scrolling, roughly ten options or more.
• Select from a large or remote dataset, such as users, audiences, or channels, where matches are fetched while the user types.
• Offer options that fall into named categories, such as Fruits and Vegetables, using grouped list sections.
• Let the user replace an existing value by typing over it, without clearing the field first.

When not to use

• Don’t use it when several options can be selected at once — use Searchable Multi Select instead.
• Don’t use it for a short, fixed list of ten or fewer options where search adds no value — 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 Radio 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 search content across a page or app rather than to set a form value — use Search Input instead.
• Don’t use it to trigger actions rather than to set a value — use Menu 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.
• Keep SearchableSingleSelect.Input inside SearchableSingleSelect.Root, so typing and the selected value share one field.
• Use Field.Description for guidance the user needs before selecting, and Field.Error for validation messages.
• Always provide SearchableSingleSelect.Empty content, so a query with no matches never leaves the popup blank.
• Constrain the width on Field.Root; the field fills its container and the popup always matches the field width.

Leading icon

• Add leadingIcon to SearchableSingleSelect.Input only when the icon says what kind of content is being selected, such as people, audiences, or languages.
• 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. Apple, instead of repeating the label.
• Don’t use the placeholder as a label — the field always needs a visible Field.Label.
• 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 SearchableSingleSelect.Group and label each group with SearchableSingleSelect.GroupLabel.
• Put a SearchableSingleSelect.Separator between groups so the sections stay visually distinct.
• The popup is capped at 272px tall, scrolls once the options exceed that height, and hugs the content when there are fewer options.
• The popup always matches the width of the field, so size the field to control how much of each option is readable.
• Options wider than the popup truncate with an ellipsis, so put the words that tell options apart at the start of the label.

Selected value and search

• The field shows the selected value as editable text; typing in an open field replaces that value and starts a new query.
• The caret icon is replaced by a search icon while the popup is open, to signal that typing filters the list.
• 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.
• A value longer than the field truncates with an ellipsis while the field is at rest, and is cut off without an ellipsis while the field has focus.
• Don’t rely on the field alone to show long values in full — keep labels short enough to be recognised when truncated.
• The clear button next to the caret appears as soon as the field has a value and removes the current selection.
• Closing the popup without picking an option keeps the value that was selected before.

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.
• Show either Field.Description or Field.Error, never both at once — the error replaces the description while validation fails.

Accessibility

• Always connect a Field.Label to the field — a placeholder is not a label.
• Keep the built-in accessible labels on the clear and open controls, or replace them with equally descriptive ones.
• Render SearchableSingleSelect.Status to announce result counts and loading state to screen reader users.
• Arrow keys move through the options, Enter selects the highlighted option, and Escape closes the popup.
• Don’t rely on the highlight colour alone to signal which option is selected — the selected value is also shown in the field.

Content and UX copy

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