ComponentsFormSelect

Select

Select lets people choose one or more values from a predefined list, with optional grouping and search for larger data sets.

Single selectMulti selectSearchableGrouped options3 sizes

Overview

Use Select when valid choices are known in advance and showing every choice at once would take too much space.

Single selection

Live preview

A label names the field and the placeholder prompts an action without pretending to be a value.

Choose the team responsible for this project.

ProjectForm.tsx
tsx
import { Select } from 'omverse-ui'
 
<Select
label="Department"
placeholder="Select a department"
options={departments}
value={department}
onChange={setDepartment}
clearable
/>

Anatomy

Select combines a field label, trigger, option list, and supporting feedback into one selection control.

Choose one department.

12345
  1. 1
    LabelRequired

    Identifies the value being selected.

  2. 2
    Trigger and valueRequired

    Displays the placeholder or current selection.

  3. 3
    Disclosure icon

    Signals that activating the field opens a list.

  4. 4
    Supporting text

    Provides guidance or validation feedback.

  5. 5
    ListboxRequired

    Contains options, groups, search, and selection state.

When to use

Choose Select when selection is safer and faster than recalling and typing an exact value.

Recommended

  • Choose from a known list

    Use for departments, statuses, owners, regions, and other governed values.

  • Conserve form space

    Use when radio buttons would make a form unnecessarily long.

  • Search larger lists

    Enable search when scanning the full option set is inefficient.

When not to use

Use a more direct control when choices are few, binary, or not predefined.

Avoid

  • Do not hide two to five important choices

    Use Radio so options can be compared without opening a list.

  • Do not use for free-form values

    Use Input when the value is not constrained to a known set.

  • Do not use as primary navigation

    Use Tabs, links, or navigation menus for moving between destinations.

Variants

Select supports single and multiple selection, optional search, grouped options, and three field sizes.

Single

Choose exactly one value from the list.

Multiple

Choose independent values displayed as removable chips.

Searchable

Filter a long list without changing its underlying options.

Grouped

Organize related options under non-selectable headings.

States

Selection state must remain clear before, during, and after the listbox interaction.

StateTriggerVisual responseInteraction
ClosedNo active interactionCurrent value or placeholderTrigger opens the list
OpenTrigger is activatedListbox and active option are visibleArrow keys move through available options
SelectedAn option is chosenLabel or chips replace the placeholderSelection can be changed or cleared
SearchSearchable list is openFilter input and matching optionsTyping narrows the available list
ErrorRequired or business validation failsError treatment and corrective messageTrigger remains available for correction
DisabledSelection is unavailableReduced emphasisCannot open or receive focus

Behavior

The trigger opens a listbox, maintains the current selection, and returns focus predictably when the list closes.

Open and close

Open from the trigger; close after a single selection, Escape, or an outside interaction.

Navigate

Move through enabled options without losing the current committed value.

Filter

Search changes the visible option set, not the stored value.

Clear

Expose a clear action only when an empty value is valid.

Accessibility

Select exposes trigger, listbox, option, selection, and validation state to assistive technology.

KeyAction
EnterSpaceOpens the list or selects the active option.
↑↓Moves through enabled options.
HomeEndMoves to the first or last enabled option.
EscCloses the list and returns focus to the trigger.
  • Provide a visible, unique label.
  • Keep selected and active option states programmatically available.
  • Do not use color as the only selected-state signal.
  • Keep disabled options discoverable but unavailable.
  • Announce validation feedback and multi-selection changes.
  • Avoid custom option content that obscures the option label.

Content guidelines

Labels and options should be concise, parallel, and easy to scan.

Name the field

Use a short noun or noun phrase for the label.

ExampleDepartment

Prompt an action

Write placeholder text that describes selection rather than a fake default.

ExampleSelect a department

Keep options parallel

Use consistent capitalization, grammar, and specificity across the list.

ExampleDesign, Engineering, Marketing

Explain invalid choices

Tell people what selection is required and why.

ExampleSelect a billing country.

Examples

Add search and multi-selection only when they make the option set easier to complete.

Searchable multi-select

Live preview

Selected values remain visible while search helps people find additional options.

Choose every technology used by this service.

Validation and availability

Live preview

Errors identify the missing choice; disabled fields communicate unavailable configuration.

Select a billing country.

Managed by your organization.

ServiceForm.tsx
tsx
<Select
label="Technologies"
options={technologies}
multi
searchable
values={technologies}
onChangeMulti={setTechnologies}
maxDisplay={3}
helperText="Choose every technology used by this service."
/>

Props / API

Select extends div attributes except onChange, which uses the selected value rather than a DOM event.

Props

PropTypeDefaultDescription
labelstringundefinedVisible label above the trigger.
aria-labelstringlabel or placeholderNames the combobox trigger when a visible Select label is supplied by its parent composition.
placeholderstring'Select…'Prompt shown when no option is selected.
helperTextstringundefinedPersistent guidance below the field.
requiredbooleanfalseMarks the selection as required.
errorbooleanfalseApplies the invalid state.
errorTextstringundefinedActionable validation feedback.
optionsSelectOption[][]Flat list of available options.
optionGroupsSelectOptionGroup[]undefinedGrouped options; takes priority over options.
valuestringundefinedControlled value in single-select mode.
valuesstring[][]Controlled values in multi-select mode.
onChange(value: string) => voidundefinedRuns after a single selection changes.
onChangeMulti(values: string[]) => voidundefinedRuns after a multi-selection changes.
multibooleanfalseAllows more than one option to be selected.
searchablebooleanfalseAdds filtering inside the open list.
searchPlaceholderstring'Search…'Prompt for the filter input.
clearablebooleanfalseAdds an action to clear the current selection.
disabledbooleanfalsePrevents opening or changing the selection.
size'sm' | 'md' | 'lg''md'Controls trigger height and type size.
maxDisplaynumber3Maximum visible chips before an overflow count.