Select

Anatomy

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

<Select.Root>
  <Select.Trigger>
    <Select.Value />
  </Select.Trigger>
  <Select.Popup>
    <Select.List>
      <Select.Item />
    </Select.List>
  </Select.Popup>
</Select.Root>

When to use

• Use a Select when the user must choose exactly one value from a list that is known in advance.
• Use a Select when the list has roughly 5 to 15 options — enough that listing them all inline would crowd the form, few enough to scan without a search field.
• Use a Select inside a form, alongside other fields, when the chosen value is saved or submitted with the form.
• Use a Select when the collapsed field should show the currently selected value at a glance.
• Use a Select when every option is a value the user sets, not an action the user runs.

When not to use

• Don’t use a Select for more than 15 options or for options loaded from a large, growing data set — use Searchable Single Select instead.
• Don’t use a Select when the user can choose more than one option — use Searchable Multi Select instead.
• Don’t use a Select for 2 to 4 options that users need to compare at a glance — use Radio instead.
• Don’t use a Select for a single on or off setting — use Switch instead.
• Don’t use a Select to switch between up to 4 views or modes — use Segmented Control instead.
• Don’t use a Select to trigger actions or navigate somewhere — use Menu instead.
• Don’t use a Select to narrow down a list or table of results — use Filter instead.
• Don’t use a Select when users may need a value that isn’t in the list — use Text Field instead.

How to use

Structure

• Wrap every Select in a Field.Root and label it with a Field.Label.
• Pass the full option list to Select.Root through items so Select.Value renders the label of the selected value in the trigger.
• Render one Select.Item per option inside Select.List, wrapped in Select.Popup.
• Add a Field.Description below the field when the choice needs clarification, and keep it to one sentence.
• Mark a required Select with requiredLabel on Field.Label and aria-required on Select.Trigger.
• Show validation problems with invalid on Field.Root and a Field.Error message — the error replaces the description, so don’t keep essential instructions in the description alone.

Options

• Order options the way users expect them: by frequency of use, alphabetically, or in a natural sequence such as dates or sizes.
• Group related options with Select.Group and a Select.GroupLabel, and divide unrelated groups with Select.Separator.
• Keep group labels to one or two words — they are headings, not selectable options.
• Include an explicit no-selection option, such as None, when an empty value is a valid result, because users cannot clear a Select once they have chosen a value.
• Remove options that can never apply in the current context instead of rendering them disabled.

Placeholder & default value

• Set defaultValue on Select.Root when a sensible default exists, so users can move on without opening the dropdown.
• Provide the placeholder as the first entry of items with value: null, so Select.Value renders it while nothing is selected.
• Write the placeholder so it names the kind of option to choose, such as Select a Space.
• Don’t replace the label with a placeholder — the placeholder disappears as soon as a value is chosen.

Icons

• Add a leadingIcon to Select.Trigger only when the icon identifies the type of content being selected, such as a Space or a page.
• Use the same leading icon for every value of one field — the icon describes the field, not the selected option.
• Don’t add decorative icons that carry no meaning for the choice.
• Don’t use country flags to represent languages, because a language is not tied to one country — use a language icon and the language name instead.

Layout & sizing

• The trigger is 40px high — keep it at least 80px wide so the value and the caret stay legible.
• Set an explicit width on Select.Trigger, such as w-80 or w-full — without one the trigger shrinks to fit its current value and changes size as the user picks different options.
• Give the field a fixed width when it sits next to other short fields, and let it fill the container when it spans a form section on its own.
• Match the field width to the expected length of the option labels so values don’t truncate needlessly.
• The dropdown always matches the width of the trigger, so option labels longer than the field truncate with an ellipsis.

Behavior & states

• The dropdown grows to a maximum height of 272px and hugs its content when there are fewer options; beyond that height it scrolls.
• The caret flips from down to up while the dropdown is open.
• Rely on the built-in hover, pressed, focus, and disabled styles instead of restyling the trigger to convey state.
• Disable the whole field only when the user can’t change the value at all, and explain why in nearby text.
• Show a loading spinner inside the dropdown while options are being fetched, so users don’t see an empty list.

Accessibility

• Always pair the Select with a visible Field.Label — placeholder text is not a label.
• Let Select.Trigger and Select.Popup provide the combobox and listbox roles instead of adding ARIA roles yourself.
• Keep keyboard support intact: Enter, Space, or the arrow keys open the dropdown, the arrow keys move between options, Enter selects, and Escape closes without changing the value.
• Never convey the selected option through color alone — the selected item is also marked with a checkmark indicator.
• Give the error message a Field.Error so it is announced, and don’t rely on the red border alone.

Content & UX copy

• Write field labels in Title Case, such as Font Family.
• Write option labels in Title Case and keep them under 3 words so they don’t truncate.
• Write placeholders in Title Case without a trailing ellipsis, such as Select Option.
• Write description text in sentence case and end it with a period.
• Write error messages in sentence case and say what to do next, such as Select a Space to continue.
• Reuse the wording users already see elsewhere in the product for the same options.