# Searchable select (goodtabs UI)

One pick from a filterable list in a popover, with a check on the current value.

## Install

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

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

## Usage

```tsx
import { SearchableSelect } from "@/components/ui/searchable-select"

<SearchableSelect
  options={[
    { value: "next", label: "Next.js" },
    { value: "astro", label: "Astro" },
  ]}
  defaultValue="next"
  placeholder="Pick a framework"
  aria-label="Framework"
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| options | `{ value: string; label: string; description?: string; disabled?: boolean }[]` |  | The choices, in order. |
| value | `string` |  | Controlled value. |
| defaultValue | `string` |  | Initial value when uncontrolled. |
| onValueChange | `(value: string) => void` |  | Called with the new value. |
| placeholder | `string` | `"Select..."` | Trigger text when nothing is chosen. |
| searchPlaceholder | `string` | `"Search..."` | Placeholder of the filter field. |
| emptyText | `string` | `"No results"` | Shown when the filter matches nothing. |
| width | `string` |  | Width of the trigger and the list, any CSS length. Fills its container by default. |

## When to use

- One choice from more than six or seven options, where typing beats scrolling
- Settings and forms: region, timezone, assignee, repository
- When each option needs a second line to tell it apart

## When not to use

- Five options or fewer; the shadcn Select or a segmented control is lighter
- Several picks at once; use the multi select
- Free text with suggestions; this only accepts listed values

## Notes for agents

- Works controlled (value, onValueChange) or uncontrolled (defaultValue); it takes functions, so render it from a client component
- The trigger is shadcn's outline Button, so every Button prop applies; give it an aria-label or pair it with a visible label
- The list filters on label and value through cmdk; the popover matches the trigger width and closes on pick
- Disabled options stay visible at half opacity and cannot be picked

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