---
title: Select
description: >-
  A compound select component for choosing from a list, with grouped options and
  controlled or uncontrolled state.
---

# Select

## Overview

Select is a form control that lets users choose an option from a predefined list. It works well for a single selection from a fixed set of known options.

```tsx
<Select.Root defaultValue="active">
	<Select.Item value="draft">Draft</Select.Item>
	<Select.Item value="active">Active</Select.Item>
	<Select.Item value="archived">Archived</Select.Item>
</Select.Root>
```

## Usage Guidelines

- **Use for a single choice:** Use Select when users need to choose one option from a fixed set. For multiple selections or custom values, use a more suitable control.
- **Write clear option labels:** Use concise, distinct labels so users can scan and compare choices quickly.
- **Order options predictably:** Arrange options in a clear, expected order, such as alphabetical, chronological, or by frequency of use.

## API Reference

### `Select.Root`

Controls selected value state and provides context for listbox rendering.

| Prop            | Type                                         | Default     |
| --------------- | -------------------------------------------- | ----------- |
| `value`         | `string`                                     | `undefined` |
| `defaultValue`  | `string`                                     | `undefined` |
| `onValueChange` | `(value: string) => void`                    | `undefined` |
| `items`         | `Array<{ value: string; label: ReactNode }>` | `undefined` |
| `children`      | `ReactNode`                                  | `undefined` |
| `disabled`      | `boolean`                                    | `false`     |

### `Select.Item`

Selectable option row inside the select popup list.

| Prop       | Type        | Default     |
| ---------- | ----------- | ----------- |
| `value`    | `string`    | `undefined` |
| `children` | `ReactNode` | `undefined` |
| `disabled` | `boolean`   | `false`     |

### `Select.Group`

Groups related `Select.Item` elements under a shared label.

| Prop       | Type        | Default     |
| ---------- | ----------- | ----------- |
| `children` | `ReactNode` | `undefined` |

### `Select.GroupLabel`

Renders the label for a grouped set of select items.

| Prop       | Type        | Default     |
| ---------- | ----------- | ----------- |
| `children` | `ReactNode` | `undefined` |

### `Select.Separator`

Visual divider between item groups in the popup list.

| Prop          | Type                         | Default        |
| ------------- | ---------------------------- | -------------- |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` |

## Examples

### Basic selection

Use Select for a single choice from a short, known set of options.

```tsx
<Select.Root defaultValue="active">
	<Select.Item value="draft">Draft</Select.Item>
	<Select.Item value="active">Active</Select.Item>
	<Select.Item value="archived">Archived</Select.Item>
</Select.Root>
```

### Grouped options

Use groups and separators to organize related options into clearer sections.

```tsx
<Select.Root defaultValue="viewer">
	<Select.Group label="Workspace">
		<Select.Item value="viewer">Viewer</Select.Item>
		<Select.Item value="editor">Editor</Select.Item>
	</Select.Group>
	<Select.Separator />
	<Select.Group label="Administration">
		<Select.Item value="billing-admin">Billing admin</Select.Item>
		<Select.Item value="owner">Owner</Select.Item>
	</Select.Group>
</Select.Root>
```

### Disabled options

Disable options that users cannot choose yet while keeping the full set of available plans or states visible.

```tsx
<Select.Root defaultValue="professional">
	<Select.Item value="starter">Starter</Select.Item>
	<Select.Item value="professional">Professional</Select.Item>
	<Select.Item value="enterprise" disabled>
		Enterprise
	</Select.Item>
</Select.Root>
```

### Controlled

Use a controlled select when the selected value needs to stay in sync with surrounding application state.

```tsx
const [value, setValue] = useState("medium");

<Select.Root value={value} onValueChange={(nextValue) => setValue(nextValue)}>
	<Select.Item value="low">Low</Select.Item>
	<Select.Item value="medium">Medium</Select.Item>
	<Select.Item value="high">High</Select.Item>
</Select.Root>
```