Select
A form field that opens a short list and takes exactly one value.
Installation
npx shadcn@latest add @flyingsalmon/selectUsage
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
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
- DoWrite 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’tPreselect 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.
- DoList 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.
- DoKeep 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’tLet 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
| Key | Description |
|---|---|
| Tab | Moves focus to the trigger. A loading trigger stays in the tab order; a disabled one leaves it. |
| EnterSpaceArrowDownArrowUp | Opens a closed trigger. Opening never changes the value. |
| ArrowDownArrowUp | Moves the highlight through the open list. |
| HomeEnd | Moves the highlight to the first or last item. |
| EnterSpace | Chooses the highlighted item and closes the list. |
| Escape | Closes 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.
| Prop | Type | Default | Description |
|---|---|---|---|
| label | string | – | The visible label. Renders above the trigger and is wired to it. |
| placeholder | string | – | Shown in the trigger while no value is chosen. |
| size | SelectSize | SelectSize.Default | Default and Small match the field heights of the same names. |
| description | string | – | Helper text under the trigger. |
| error | string | – | The failure message. Turns the border, the ring, and the label destructive. |
| loading | boolean | false | Swaps the chevron for a spinner and blocks opening. The trigger keeps focus and shows its value. |
| side | PanelSide | PanelSide.Bottom | Which side of the trigger the list opens on. |
| align | PanelAlign | PanelAlign.Center | How the list aligns to the trigger on that side. |
SelectItem
Also takes every <div> attribute.
| Prop | Type | Default | Description |
|---|---|---|---|
| value | string | Required | The value the select reports when this item is chosen. |
| children | string | Required | The item text, as a plain string. It is also what the trigger shows and what typeahead matches. |
| icon | ReactNode | – | An icon ahead of the text. Hidden from screen readers and not shown in the trigger. |
| disabled | boolean | false | Dims the item and keeps it in the list. |
SelectGroup, SelectLabel, and SelectSeparator take their element’s props.