Select

Picks one option from a compact list.

Code

import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select"
import { Field, FieldControl, FieldLabel } from "@/components/ui/field"

<Field required>
  <FieldLabel>Country</FieldLabel>
  <Select>
    <FieldControl>
      <SelectTrigger>
        <SelectValue placeholder="Choose a country" />
      </SelectTrigger>
    </FieldControl>
    <SelectContent>
      <SelectItem value="BR">Brazil</SelectItem>
      <SelectItem value="CA">Canada</SelectItem>
      <SelectItem value="US">United States</SelectItem>
    </SelectContent>
  </Select>
</Field>

Examples

Example source

var P = window.PUI, h = React.createElement;
  ReactDOM.createRoot(document.getElementById('preview')).render(h('div', { className: 'pui-field' },
    h(P.Label, { htmlFor: 'country' }, 'Country'),
    h(P.Select, { id: 'country', defaultValue: 'US', options: [
      { value: 'BR', label: 'Brazil' }, { value: 'CA', label: 'Canada' },
      { value: 'MX', label: 'Mexico' }, { value: 'US', label: 'United States' }] })));

Usage

What you provide

Select > SelectTrigger (SelectValue inside) + SelectContent with one SelectItem per option. size: sm | default.
A linked Label; options with short labels in a logical order (alphabetical, or by frequency).
Up to ~15 options. Beyond that, use an Autocomplete (combobox) with search.
Two to four options that should stay visible: prefer RadioGroup or Tabs.

Accessibility

The field has a persistent label (use Field); help and errors are tied to it. A placeholder never replaces the label.
Hover and focus give visible feedback. Clicking the field opens the list; choosing an option updates the visible value; clicking outside closes it.
Keyboard: Tab reaches the field; Enter, Space or arrows open it; arrows move between options; Enter confirms; Esc closes without changing the value; focus is never trapped.
Screen readers hear the label, the current value and that options are available. The list follows the listbox pattern; never put buttons or links inside options.
To search through options, use an Autocomplete (combobox) pattern instead; for a few options that should stay visible, use radio buttons or checkboxes.

Adapted from Magoo 1.6.0 by Marcelo Sales: Select (select), Autocomplete (autocomplete). Magoo is educational guidance; test the behavior in your implementation.

API

Install with:

npx @aline-aroucha/pui add select

<Select>
  <SelectTrigger>
    <SelectValue />
  </SelectTrigger>
  <SelectContent>
    <SelectGroup>
      <SelectLabel />
      <SelectItem />
    </SelectGroup>
    <SelectSeparator />
  </SelectContent>
</Select>

Select

Name	Type	Default
`value`	`string`	—
Controlled value.
`defaultValue`	`string`	—
Initial value when uncontrolled.
`onValueChange`	`(value: string) => void`	—
Runs when an option is chosen.
`disabled`	`boolean`	`false`
Blocks opening.
`required`	`boolean`	`false`
A value is needed to submit.
`name`	`string`	—
Form field name.

SelectTrigger

Name	Type	Default
`size`	`"sm" \| "default"`	`"default"`
Field height.

SelectValue

Name	Type
`placeholder`	`string`
Shown before a value is chosen.

SelectItem

Name	Type	Default
`value`Required	`string`	—
Option value.
`disabled`	`boolean`	`false`
Option can't be chosen.