# Grouped select (goodtabs UI)

The house select: placeholder, labelled option groups, disabled items and a width.

## Install

```bash
npx shadcn@latest add https://ui.goodtabs.co/r/grouped-select.json
```

Or, with the @goodtabs namespace configured in components.json: `npx shadcn@latest add @goodtabs/grouped-select`

## Usage

```tsx
import { GroupedSelect } from "@/components/ui/grouped-select"

<GroupedSelect
  placeholder="Timezone"
  width="100%"
  groups={[{ label: "Europe", options: [{ value: "europe/london", label: "London" }] }]}
  onValueChange={setTimezone}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| groups | `{ label: string; options: { value: string; label: string; disabled?: boolean }[] }[]` |  | The groups, each with a heading and its options. |
| value, defaultValue, onValueChange | `radix Select props` |  | Controlled or uncontrolled, as in shadcn select. |
| placeholder | `string` | `"Select"` | Text shown before a value is chosen. |
| width | `string` |  | Width of the trigger, any CSS length such as "200px" or "100%". Fits its content by default. |
| size | `"sm" | "default"` | `"default"` | Trigger height: 28px or 32px. |

## When to use

- For one choice from a list long enough to need headings
- In forms and settings panels, under a Label
- As the default select everywhere, so every select on the site looks the same

## When not to use

- For lists that need search or free text, use a combobox
- For two to five choices that should all be visible, use segmented tabs or radio cards
- For picking several values, use a filter menu

## Notes for agents

- Radix Select underneath: value, defaultValue, onValueChange, name and disabled work as in shadcn select
- width is a CSS length; without it the trigger fits its content, so set width="100%" in form rows
- A single group still needs a label; pass one group for a flat list
- Name the control with a Label and htmlFor plus an id, or an aria-label

Docs: https://ui.goodtabs.co/components/grouped-select