Skip to content
flyingsalmon

Select

A form field that opens a short list and takes exactly one value.

Installation

npx shadcn@latest add @flyingsalmon/select

Usage

import { useState } from 'react'

import { Select, SelectItem } from '@/components/ui/select'

export function SelectUsage() {
  const [currency, setCurrency] = useState<string>()

  return (
    <Select
      label="Currency"
      placeholder="Choose a currency"
      value={currency}
      onValueChange={setCurrency}
    >
      <SelectItem value="usd">US Dollar</SelectItem>
      <SelectItem value="eur">Euro</SelectItem>
      <SelectItem value="vnd">Vietnamese Dong</SelectItem>
    </Select>
  )
}

Examples

Sizes

Two trigger sizes match Input and Button. Items inside the panel stay the same height at both, because a list is dense by nature.

Groups

Open the trigger. Groups take a label and a separator, the checked item shows a mark in a reserved slot, and a disabled item stays in the list so positions never shift.

Description

Helper text sits under the trigger and joins its accessible description.

Prices show in this currency

Error

The message renders under the trigger. It can be covered while the panel is open and reappears once it closes.

Choose a supported currency

Loading

Choose who can see the trip. The trigger shows a spinner while the change saves, the card shows the result, and Anyone with the link fails and becomes the field's own error.

Lisbon long weekend

Visible to: Only you

Disabled

The trigger and its label dim together and leave the tab order. Say why in the description.

Fixed once the first payment is made

Long lists

The panel matches the trigger's width and scrolls inside a maximum height. Long item text ends in an ellipsis, and so does the chosen label in the trigger.

Guidelines

When to use

  • To choose one value from a short, fixed list: a currency, a travel style, who can see a trip.
  • When the options need groups, icons, or a disabled entry that stays visible.

When not to use

  • Use Combobox when the list is long enough that the traveller must search, or the options arrive from a server.
  • Use Radio group for two to five options that should all stay visible while the traveller decides.
  • Use Toggle group when a short set of options changes a view or a filter rather than a field value.

Do and don’t

  • Do
    Write each item as a phrase that finishes the label’s decision, such as "Move to Day 3 · 12 Oct".The label and the choice read as one sentence, and the trigger shows the same phrase once it is chosen, so the answer explains itself.
  • Don’t
    Preselect an answer that changes the trip.An empty trigger with an instruction such as "Choose where it goes" makes the choice deliberate. Left unanswered, the field fails on submit with a message that names the choice.
  • Do
    List an opt-out such as "Drop it" first, in plain text like every other item.Leaving something out is a fair answer, not a warning. First place makes it easy to find without making it louder than the rest.
  • Do
    Keep a sold-out or unavailable option in the list, disabled.The list keeps its shape, and the traveller sees the option exists instead of wondering where it went.
  • Don’t
    Let an item’s icon say something its text does not.The icon only decorates. The trigger shows the text alone once the item is chosen, so the words must carry the whole meaning.

Accessibility

KeyDescription
TabMoves focus to the trigger. A loading trigger stays in the tab order; a disabled one leaves it.
EnterSpaceArrowDownArrowUpOpens a closed trigger. Opening never changes the value.
ArrowDownArrowUpMoves the highlight through the open list.
HomeEndMoves the highlight to the first or last item.
EnterSpaceChooses the highlighted item and closes the list.
EscapeCloses the list with no change.

Typing characters moves the highlight to the next matching item. Focus always returns to the trigger when the list closes. Select generates the trigger id and wires the label to it, so clicking the label focuses the trigger without opening the list. An error sets aria-invalid, and aria-describedby lists any ids you passed, then the error message, then the description. A loading trigger sets aria-busy. required marks the label, sets aria-required, and takes part in native validation. The states every field shares are described on Fields.

API

Select

Also takes value, defaultValue, onValueChange, open, defaultOpen, onOpenChange, name, disabled, and required. className styles the wrapper.

PropTypeDefaultDescription
labelstring–The visible label. Renders above the trigger and is wired to it.
placeholderstring–Shown in the trigger while no value is chosen.
sizeSelectSizeSelectSize.DefaultDefault and Small match the field heights of the same names.
descriptionstring–Helper text under the trigger.
errorstring–The failure message. Turns the border, the ring, and the label destructive.
loadingbooleanfalseSwaps the chevron for a spinner and blocks opening. The trigger keeps focus and shows its value.
sidePanelSidePanelSide.BottomWhich side of the trigger the list opens on.
alignPanelAlignPanelAlign.CenterHow the list aligns to the trigger on that side.

SelectItem

Also takes every <div> attribute.

PropTypeDefaultDescription
valuestringRequiredThe value the select reports when this item is chosen.
childrenstringRequiredThe item text, as a plain string. It is also what the trigger shows and what typeahead matches.
iconReactNode–An icon ahead of the text. Hidden from screen readers and not shown in the trigger.
disabledbooleanfalseDims the item and keeps it in the list.

SelectGroup, SelectLabel, and SelectSeparator take their element’s props.

  • Fields

    The label, description, error, loading, and disabled behaviour every field shares.
  • Combobox

    The searchable field for long or remote lists.
  • Radio group

    Keeps a few options visible at once.
  • Form

    Lays fields out with an actions row and a result slot.