# Select

Picks one option from a compact list.

```tsx
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>
```

## 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](https://magoo.cc/en/components/forms/select.html) (`select`), [Autocomplete](https://magoo.cc/en/components/forms/autocomplete.html) (`autocomplete`). Magoo is educational guidance; test the behavior in your implementation._

## API

Install:

```bash
npx @aline-aroucha/pui add select
```

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

### Select

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `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 | Description |
| --- | --- | --- | --- |
| `size` | `"sm" \| "default"` | `"default"` | Field height. |

### SelectValue

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `placeholder` | `string` | — | Shown before a value is chosen. |

### SelectItem

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `string` | — | Option value. |
| `disabled` | `boolean` | `false` | Option can't be chosen. |

## Related pages

- [Field](https://aline-aroucha.github.io/pui/components/field.html)
- [Checkbox](https://aline-aroucha.github.io/pui/components/checkbox.html)
- [Tabs](https://aline-aroucha.github.io/pui/components/tabs.html)

---
PUI documentation · https://aline-aroucha.github.io/pui/components/select.html