# Select

Select,
SelectContent,
SelectGroup,
SelectItem,
SelectLabel,
SelectSeparator,
SelectTrigger,
} from "@/components/starwind/select";

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
} from "@/components/starwind/select";
---

<Select name="framework" defaultValue="astro" required>
  <SelectTrigger placeholder="Choose a framework" />
  <SelectContent>
    <SelectItem value="astro">Astro</SelectItem>
    <SelectItem value="react">React</SelectItem>
    <SelectItem value="vue">Vue</SelectItem>
  </SelectContent>
</Select>
```
  </div>
  <div slot="react">
```tsx
import {
      Select,
      SelectContent,
      SelectItem,
      SelectTrigger,
    } from "@/components/starwind/select";

export function Example() {
  return (
    <>
      <Select name="framework" defaultValue="astro" required>
            <SelectTrigger placeholder="Choose a framework" />
            <SelectContent>
              <SelectItem value="astro">Astro</SelectItem>
              <SelectItem value="react">React</SelectItem>
              <SelectItem value="vue">Vue</SelectItem>
            </SelectContent>
          </Select>
    </>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

> **Info:** Form props such as `name`, `required`, `readOnly`, and `defaultValue` belong on `Select`. The
trigger now focuses on presentation and uses its `placeholder` prop for the installed value part.

## Installation

```bash
npx starwind@latest add select
```

## Usage

### Form participation

Select serializes its value through a hidden input and follows native form reset behavior.

```astro
<form>
  <Select name="role" required>
    <SelectTrigger placeholder="Choose a role" />
    <SelectContent>
      <SelectItem value="admin">Administrator</SelectItem>
      <SelectItem value="member">Member</SelectItem>
    </SelectContent>
  </Select>
  <button type="submit">Save</button>
</form>
```

### Programmatic value changes

Dispatch `starwind:set-value` on the Select root. Listen for the root-scoped
`starwind:value-change` event when the selected value changes.

```astro
<Select id="role-select" name="role">
  <SelectTrigger placeholder="Choose a role" />
  <SelectContent>
    <SelectItem value="admin">Administrator</SelectItem>
    <SelectItem value="member">Member</SelectItem>
  </SelectContent>
</Select>

<button id="choose-admin" type="button">Choose administrator</button>

<script>
  const select = document.querySelector<HTMLElement>("#role-select");
  const button = document.querySelector<HTMLElement>("#choose-admin");

  button?.addEventListener("click", () => {
    select?.dispatchEvent(
      new CustomEvent("starwind:set-value", {
        detail: { value: "admin" },
      }),
    );
  });

  select?.addEventListener("starwind:value-change", (event) => {
    const { value } = (event as CustomEvent<{ value: string | null }>).detail;
    console.log(value);
  });
</script>
```

> **Info:** The legacy document-wide selection event has been replaced by the root-targeted
`starwind:set-value` command, preventing unrelated Select instances from doing extra work.

For a searchable text input with listbox suggestions, install [Combobox](/docs/components/combobox)
instead of adding the removed search part.

## Framework Availability
Select is available for Astro and React.
Astro available; React available
| Framework | Status | Notes |
| --- | --- | --- |
| Astro | available | - |
| React | available | - |
## API Reference
### Select
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `defaultOpen` | `boolean` | No | `false` | Primitive override | Sets the initial open state when the component is uncontrolled. |
| `disabled` | `boolean` | No | `false` | Primitive override | Disables interaction with the component. |
| `required` | `boolean` | No | `false` | Primitive override | Marks the control as required for form validation. |
- Inherits div attributes. Omits `defaultValue` and `onChange`.

### SelectTrigger
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `asChild` | `boolean` | No | `false` | Primitive override | Merges the component behavior and props into its child element. |
| `iconClass` | `string` | No | - | Wrapper prop | Adds classes to the component's generated icon. |
| `placeholder` | `string` | No | - | Wrapper prop | Provides fallback text for the value element generated inside the trigger. |
| `showIcon` | `boolean` | No | `true` | Wrapper prop | Shows the component's generated icon. |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Styled variant | Selects the component's visual size. |
| `valueClass` | `string` | No | - | Wrapper prop | Adds classes to the generated value element. |
- Inherits button attributes.

### SelectValue
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `placeholder` | `string` | No | - | Wrapper prop | Provides fallback text when no value is available. |
- Inherits span attributes.

### SelectContent
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Wrapper prop | Selects the component's visual size. |
- Inherits div attributes.

### SelectItem
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `disabled` | `boolean` | No | `false` | Styled variant | Disables interaction with the component. |
| `indicatorClass` | `string` | No | - | Wrapper prop | Adds classes to the generated selection indicator. |
| `inset` | `boolean` | No | `false` | Styled variant | Adds leading inset spacing for visual alignment. |
| `showIndicator` | `boolean` | No | `true` | Wrapper prop | Shows the generated selection indicator. |
| `value` | `string` | Yes | - | Primitive override | Controls or identifies the component value. |
- Inherits div attributes. Omits `role`.

### SelectItemText
- Inherits span attributes.

### SelectItemIndicator
- Inherits span attributes.

### SelectGroup
- Inherits div attributes.

### SelectLabel
- Inherits div attributes.

### SelectSeparator
- Inherits div attributes.

### SelectScrollUpButton
- Inherits div attributes.

### SelectScrollDownButton
- Inherits div attributes.
### Primitive And Runtime API
Behavior, state, events, form participation, and imperative methods are documented in the lower-level references.
- Primitive: [Select Primitive](/docs/primitives/select/)
- Runtime factory: [`createSelect`](/docs/runtime/#create-select) from `@starwind-ui/runtime/select`

## Changelog

### v2.0.0

- Rebuilt Select on Starwind Runtime for selection, forms, events, and scroll behavior; search is now provided by Combobox.
- See the [Select Primitive](/docs/primitives/select/) for the underlying unstyled anatomy and behavior API.