docs / core / select

Select

one value from a closed list, revealed when you open its trigger. for a long set of known options; a few visible choices want SegmentedControl or Radio.

intensity · recedesrsc · client

provenance

authored in usva

layer

core / primitives

intensity

recedes · safe anywhere, including dense surfaces

composition

form rows next to Input, sharing the same height and focus ringfilter bars where the options are known and shortnot for two or three options. that is SegmentedControlnot for navigation. picking an option should never route

a11y

the trigger is a combobox, the popup a listbox of options · give a trigger with no visible label an aria-labeljest-axe

dependencies

@base-ui/react
live demo · try it out
customize
placeholdershown until a value is picked
defaultValuethe value chosen on mount
disableddims the trigger, blocks the popup
usagecopy
import { Select } from "@usva-ui/react/primitives/select";

<Select>
  <Select.Trigger aria-label="Fruit">
    <Select.Value placeholder="Pick a fruit" />
  </Select.Trigger>
  <Select.Content>
    <Select.Item value="apple">Apple</Select.Item>
    <Select.Item value="banana">Banana</Select.Item>
    <Select.Item value="cherry">Cherry</Select.Item>
  </Select.Content>
</Select>

props

proptypedefaultnotes
valueValue | null—the controlled selection. pair with onValueChange.
defaultValueValue | null—starting selection when uncontrolled.
onValueChange(value, eventDetails) => void—fires with the new value when the user picks one.
namestring—the form field name. a hidden input carries the value.
disabledbooleanfalsedims the trigger to 50% and blocks the popup.
Content sideOffsetnumber6the gap between trigger and listbox.

get it

bun add @usva-ui/reactcopy
usagecopy
import { Select } from "@usva-ui/react/primitives/select";

<Select onValueChange={(value) => setFruit(value)}>
  <Select.Trigger aria-label="Fruit">
    <Select.Value placeholder="Pick a fruit" />
  </Select.Trigger>
  <Select.Content>
    <Select.Item value="apple">Apple</Select.Item>
    <Select.Item value="banana">Banana</Select.Item>
  </Select.Content>
</Select>