# Combobox

Combobox,
ComboboxContent,
ComboboxEmpty,
ComboboxGroup,
ComboboxGroupLabel,
ComboboxInput,
ComboboxItem,
ComboboxLabel,
ComboboxSeparator,
} from "@/components/starwind/combobox";

<FrameworkCodeSwitcher>
  <div slot="astro">
```astro
---
import {
  Combobox,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxLabel,
} from "@/components/starwind/combobox";
---

<Combobox name="framework" defaultValue="astro" required>
  <ComboboxLabel>Framework</ComboboxLabel>
  <ComboboxInput placeholder="Search frameworks" showClear />
  <ComboboxContent>
    <ComboboxEmpty>No framework found.</ComboboxEmpty>
    <ComboboxItem value="astro">Astro</ComboboxItem>
    <ComboboxItem value="react">React</ComboboxItem>
    <ComboboxItem value="vue">Vue</ComboboxItem>
  </ComboboxContent>
</Combobox>
```
  </div>
  <div slot="react">
```tsx
import {
  Combobox,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxLabel,
} from "@/components/starwind/combobox";

export function Example() {
  return (
    <Combobox name="framework" defaultValue="astro" required>
      <ComboboxLabel>Framework</ComboboxLabel>
      <ComboboxInput placeholder="Search frameworks" showClear />
      <ComboboxContent>
        <ComboboxEmpty>No framework found.</ComboboxEmpty>
        <ComboboxItem value="astro">Astro</ComboboxItem>
        <ComboboxItem value="react">React</ComboboxItem>
        <ComboboxItem value="vue">Vue</ComboboxItem>
      </ComboboxContent>
    </Combobox>
  );
}
```
  </div>
</FrameworkCodeSwitcher>

> **Info:** Combobox is now its own CLI-installed Runtime component. Use its input, content, and item parts
instead of the removed Select search composition.

## Installation

```bash
npx starwind@latest add combobox
```

## Usage

### Filtering and clearing

`filterMode` controls built-in matching. `showClear` renders the installed clear control inside the
input group.

```astro
<Combobox filterMode="startsWith" locale="en">
  <ComboboxInput aria-label="Fruit" placeholder="Search fruit" showClear />
  <ComboboxContent>
    <ComboboxEmpty>No fruit found.</ComboboxEmpty>
    <ComboboxItem value="apple">Apple</ComboboxItem>
    <ComboboxItem value="apricot">Apricot</ComboboxItem>
    <ComboboxItem value="banana">Banana</ComboboxItem>
  </ComboboxContent>
</Combobox>
```

> **Info:** Filtering, empty state, keyboard navigation, selection, and form serialization are managed by the
Combobox Runtime rather than a page-local search script. The input keeps an explicit accessible
name even when the compact example omits a visible label.

## Framework Availability
Combobox is available for Astro and React.
Astro available; React available
| Framework | Status | Notes |
| --- | --- | --- |
| Astro | available | - |
| React | available | - |
## API Reference
### Combobox
| 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`.

### ComboboxLabel
- Inherits div attributes.

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

### ComboboxInput
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `showClear` | `boolean` | No | `false` | Wrapper prop | Shows the generated clear-value control. |
| `showTrigger` | `boolean` | No | `true` | Wrapper prop | Shows the generated popup trigger. |
- Inherits input attributes.

### ComboboxTrigger
| 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. |
| `showIcon` | `boolean` | No | `true` | Wrapper prop | Shows the component's generated icon. |
- Inherits button attributes.

### ComboboxClear
| Prop | Type | Required | Default | Kind | Description |
| --- | --- | --- | --- | --- | --- |
| `asChild` | `boolean` | No | `false` | Primitive override | Merges the component behavior and props into its child element. |
| `showIcon` | `boolean` | No | `true` | Wrapper prop | Shows the component's generated icon. |
- Inherits button attributes.

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

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

### ComboboxEmpty
- Inherits div attributes.

### ComboboxItem
| 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`.

### ComboboxItemText
- Inherits span attributes.

### ComboboxItemIndicator
- Inherits span attributes.

### ComboboxGroup
- Inherits div attributes.

### ComboboxGroupLabel
- Inherits div attributes.

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

## Changelog

### v1.0.0

- Added the dedicated Runtime-backed Combobox with filtering and clearing, replacing the legacy Select search pattern.
- See the [Combobox Primitive](/docs/primitives/combobox/) for the underlying unstyled anatomy and behavior API.