Skip to content

Select ​

Pick one option from a list of more than about five. Use radio-group when every option should be visible, and combobox when the list needs filtering.

Usage ​

vue
<Label for="country">Country</Label>
<Select v-model="country" name="country">
  <SelectTrigger id="country" placeholder="Choose a country" />
  <SelectContent>
    <SelectItem value="de">Germany</SelectItem>
    <SelectItem value="fr">France</SelectItem>
  </SelectContent>
</Select>

Props ​

PartPropTypeDefaultNotes
SelectmodelValuestringnonev-model; the chosen item's value
Selectopenbooleannonev-model:open
Selectdisabledbooleanfalse
SelectnamestringnoneForm field name; submits the chosen value
SelectrequiredbooleanfalseBlocks submit until one is chosen; needs name
SelectTriggersize'md' | 'sm' | 'lg''md'Same heights as input
SelectTriggerinvalidbooleanfalseSets aria-invalid and the danger border
SelectTriggerplaceholderstringnoneShown while nothing is chosen
SelectItemvaluestringnoneRequired
SelectItemdisabledbooleanfalse

With a name, the select takes part in its form like a native select: a choice fires input and change, autocomplete on Select lets browser autofill pick an option, and a form reset keeps the shown choice (the v-model value). Without a name it isn't part of the form.

Every part except Select takes class, merged last. Select renders no element of its own. Attributes on SelectTrigger (id, aria-*) go to the trigger button, so a label with for names it.

Slots ​

PartSlotContent
SelectdefaultThe trigger and the content
SelectContentdefaultItems, groups and separators
SelectItemdefaultThe option's text
SelectGroupdefaultA label and items
SelectLabeldefaultThe group's heading

Events ​

PartEventPayloadWhen
Selectupdate:modelValuestring | undefinedAn item is chosen
Selectupdate:openboolean | undefinedThe list opens or closes

Tokens ​

None of its own. The trigger shares input's radius (--h-input-radius) and colours; the list is surface-raised with shadow-md, stacked at z-popover.

States ​

empty with placeholder, chosen; hover, focus-visible, open; invalid; disabled trigger, disabled item; three sizes; groups with labels and a separator; a list longer than the viewport (scrolls).

Keyboard ​

KeyAction
Enter, Space, ArrowDown, ArrowUpOpen the list on the trigger
ArrowDown, ArrowUpMove between items, skipping disabled ones
Enter, SpaceChoose the highlighted item and close
LettersJump to the next item starting with them
EscapeClose without choosing; focus returns to the trigger

Accessibility ​

  • The trigger is a button with role="combobox", aria-expanded and aria-controls; the list is role="listbox" with role="option" items.
  • Name the trigger with a label (for its id) or aria-label.
  • The chosen item shows a check icon (aria-hidden) and has aria-selected="true".

Do ​

vue
<Select v-model="role">
  <SelectTrigger aria-label="Role" placeholder="Choose a role" />
  <SelectContent>
    <SelectGroup>
      <SelectLabel>Staff</SelectLabel>
      <SelectItem value="admin">Admin</SelectItem>
      <SelectItem value="editor">Editor</SelectItem>
    </SelectGroup>
  </SelectContent>
</Select>

Do not ​

vue
<!-- Two options: use a radio group, or a switch for on/off. -->
<Select v-model="billing">
  <SelectTrigger aria-label="Billing" />
  <SelectContent>
    <SelectItem value="monthly">Monthly</SelectItem>
    <SelectItem value="yearly">Yearly</SelectItem>
  </SelectContent>
</Select>