Searchable Single Select

Anatomy

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

<SearchableSingleSelect.Root>
  <SearchableSingleSelect.Input />
  <SearchableSingleSelect.Popup>
    <SearchableSingleSelect.Empty />
    <SearchableSingleSelect.List>
      <SearchableSingleSelect.Item />
    </SearchableSingleSelect.List>
  </SearchableSingleSelect.Popup>
</SearchableSingleSelect.Root>;

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.