# Combobox

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

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

<Combobox name="framework" required>
  <ComboboxLabel>Framework</ComboboxLabel>
  <ComboboxInput placeholder="Search frameworks" />
  <ComboboxContent>
    <ComboboxEmpty>No framework found.</ComboboxEmpty>
    <ComboboxItem value="astro">Astro</ComboboxItem>
    <ComboboxItem value="react">React</ComboboxItem>
    <ComboboxItem value="vue">Vue</ComboboxItem>
    <ComboboxItem value="svelte">Svelte</ComboboxItem>
    <ComboboxItem value="solid">Solid</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" required>
      <ComboboxLabel>Framework</ComboboxLabel>
      <ComboboxInput placeholder="Search frameworks" />
      <ComboboxContent>
        <ComboboxEmpty>No framework found.</ComboboxEmpty>
        <ComboboxItem value="astro">Astro</ComboboxItem>
        <ComboboxItem value="react">React</ComboboxItem>
        <ComboboxItem value="vue">Vue</ComboboxItem>
        <ComboboxItem value="svelte">Svelte</ComboboxItem>
        <ComboboxItem value="solid">Solid</ComboboxItem>
      </ComboboxContent>
    </Combobox>
  );
}
```
  </div>
  <div slot="vue">
```vue
<script setup lang="ts">
import {
  Combobox,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxLabel,
} from "@/components/starwind/combobox";
</script>

<template>
  <Combobox name="framework" required>
    <ComboboxLabel>Framework</ComboboxLabel>
    <ComboboxInput placeholder="Search frameworks" />
    <ComboboxContent>
      <ComboboxEmpty>No framework found.</ComboboxEmpty>
      <ComboboxItem value="astro">Astro</ComboboxItem>
      <ComboboxItem value="react">React</ComboboxItem>
      <ComboboxItem value="vue">Vue</ComboboxItem>
      <ComboboxItem value="svelte">Svelte</ComboboxItem>
      <ComboboxItem value="solid">Solid</ComboboxItem>
    </ComboboxContent>
  </Combobox>
</template>
```
  </div>
</FrameworkCodeSwitcher>

## Installation

```bash
npx starwind@latest add combobox --framework astro
```
</DocsTabsContent>
```bash
npx starwind@latest add combobox --framework react
```
</DocsTabsContent>
```bash
npx starwind@latest add combobox --framework vue
```
</DocsTabsContent>
</DocsTabs>

## Usage

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

<Combobox name="framework" required>
  <ComboboxLabel>Framework</ComboboxLabel>
  <ComboboxInput placeholder="Search frameworks" />
  <ComboboxContent>
    <ComboboxEmpty>No framework found.</ComboboxEmpty>
    <ComboboxItem value="astro">Astro</ComboboxItem>
    <ComboboxItem value="react">React</ComboboxItem>
    <ComboboxItem value="vue">Vue</ComboboxItem>
    <ComboboxItem value="svelte">Svelte</ComboboxItem>
    <ComboboxItem value="solid">Solid</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" required>
      <ComboboxLabel>Framework</ComboboxLabel>
      <ComboboxInput placeholder="Search frameworks" />
      <ComboboxContent>
        <ComboboxEmpty>No framework found.</ComboboxEmpty>
        <ComboboxItem value="astro">Astro</ComboboxItem>
        <ComboboxItem value="react">React</ComboboxItem>
        <ComboboxItem value="vue">Vue</ComboboxItem>
        <ComboboxItem value="svelte">Svelte</ComboboxItem>
        <ComboboxItem value="solid">Solid</ComboboxItem>
      </ComboboxContent>
    </Combobox>
  );
}
```
  </div>
  <div slot="vue">
```vue
<script setup lang="ts">
import {
  Combobox,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxLabel,
} from "@/components/starwind/combobox";
</script>

<template>
  <Combobox name="framework" required>
    <ComboboxLabel>Framework</ComboboxLabel>
    <ComboboxInput placeholder="Search frameworks" />
    <ComboboxContent>
      <ComboboxEmpty>No framework found.</ComboboxEmpty>
      <ComboboxItem value="astro">Astro</ComboboxItem>
      <ComboboxItem value="react">React</ComboboxItem>
      <ComboboxItem value="vue">Vue</ComboboxItem>
      <ComboboxItem value="svelte">Svelte</ComboboxItem>
      <ComboboxItem value="solid">Solid</ComboboxItem>
    </ComboboxContent>
  </Combobox>
</template>
```
  </div>
</FrameworkCodeSwitcher>

## Composition

Use this structure for a labeled combobox with a flat list of options:

```text
Combobox
├── ComboboxLabel
├── ComboboxInput
└── ComboboxContent
    ├── ComboboxEmpty
    └── ComboboxItem
```

`ComboboxInput` includes its trigger and can show a clear button. Use `ComboboxInputGroup` when you
need to compose `ComboboxInput`, `ComboboxValue`, `ComboboxTrigger`, or `ComboboxClear` yourself.
Groups can contain `ComboboxGroupLabel` and items. Use `ComboboxSeparator` between groups.

## Sizes

`ComboboxInput` owns the input-side `sm`, `md`, or `lg` size. `ComboboxContent` sizes the
portaled popup independently, so both scopes can match or differ.

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

{(["sm", "md", "lg"] as const).map((size) => (
  <Combobox defaultValue="astro">
    <ComboboxInput size={size} placeholder={`${size} control`} />
    <ComboboxContent size={size}>
      <ComboboxItem value="astro">Astro</ComboboxItem>
      <ComboboxItem value="react">React</ComboboxItem>
      <ComboboxItem value="vue">Vue</ComboboxItem>
    </ComboboxContent>
  </Combobox>
))}

<Combobox defaultValue="astro">
  <ComboboxInput size="sm" placeholder="Compact control" />
  <ComboboxContent size="lg">
    <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,
  ComboboxInput,
  ComboboxItem,
} from "@/components/starwind/combobox";

export function Example() {
  return (
    <>
      {(["sm", "md", "lg"] as const).map((size) => (
        <Combobox key={size} defaultValue="astro">
          <ComboboxInput size={size} placeholder={`${size} control`} />
          <ComboboxContent size={size}>
            <ComboboxItem value="astro">Astro</ComboboxItem>
            <ComboboxItem value="react">React</ComboboxItem>
            <ComboboxItem value="vue">Vue</ComboboxItem>
          </ComboboxContent>
        </Combobox>
      ))}

      <Combobox defaultValue="astro">
        <ComboboxInput size="sm" placeholder="Compact control" />
        <ComboboxContent size="lg">
          <ComboboxItem value="astro">Astro</ComboboxItem>
          <ComboboxItem value="react">React</ComboboxItem>
          <ComboboxItem value="vue">Vue</ComboboxItem>
        </ComboboxContent>
      </Combobox>
    </>
  );
}
```
  </div>
  <div slot="vue">
```vue
<script setup lang="ts">
import {
  Combobox,
  ComboboxContent,
  ComboboxInput,
  ComboboxItem,
} from "@/components/starwind/combobox";
</script>

<template>
  <template v-for="size in ['sm', 'md', 'lg'] as const" :key="size"
    ><Combobox defaultValue="astro">
      <ComboboxInput :size="size" :placeholder="`${size} control`" />
      <ComboboxContent :size="size">
        <ComboboxItem value="astro">Astro</ComboboxItem>
        <ComboboxItem value="react">React</ComboboxItem>
        <ComboboxItem value="vue">Vue</ComboboxItem>
      </ComboboxContent>
    </Combobox></template
  >

  <Combobox defaultValue="astro">
    <ComboboxInput size="sm" placeholder="Compact control" />
    <ComboboxContent size="lg">
      <ComboboxItem value="astro">Astro</ComboboxItem>
      <ComboboxItem value="react">React</ComboboxItem>
      <ComboboxItem value="vue">Vue</ComboboxItem>
    </ComboboxContent>
  </Combobox>
</template>
```
  </div>
</FrameworkCodeSwitcher>

## Filtering and clearing

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

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

<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>
```
  </div>
  <div slot="react">
```tsx
import { Combobox, ComboboxContent, ComboboxEmpty, ComboboxInput, ComboboxItem } from "@/components/starwind/combobox";

export function Example() {
  return (
    <>
      <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>
    </>
  );
}
```
  </div>
  <div slot="vue">
```vue
<script setup lang="ts">
import {
  Combobox,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
} from "@/components/starwind/combobox";
</script>

<template>
  <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>
</template>
```
  </div>
</FrameworkCodeSwitcher>

## 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. |
| `size` | `"sm" \| "md" \| "lg"` | No | `"md"` | Styled variant | Selects the component's visual size. |
- Inherits input attributes. Omits `size`.

### 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 |
| --- | --- | --- | --- | --- | --- |
| `disablePortal` | `boolean` | No | `false` | Wrapper prop | Keeps the public Portal wrapper inline instead of moving it to a target. |
| `portalContainer` | `string` | No | - | Wrapper prop | Sets the CSS selector for the public Portal wrapper target. |
| `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.2.1

- Connected group headings to their groups with `aria-labelledby` so assistive technology can identify each group.

### v1.2.0

- Added `portalContainer` and `disablePortal` to `ComboboxContent` for custom portal targets and
inline rendering.

### v1.1.0

- The popup now closes with fade and scale motion without sliding toward the trigger.
- `ComboboxInput` now accepts `size="sm"`, `size="md"`, or `size="lg"` and keeps the built-in
trigger and chevron at every size. `ComboboxContent` continues to size the popup independently.
- `ComboboxInputGroup` remains available for advanced custom composition.

### v1.0.2

- Named the generated aggregate default export so React and Astro tooling can identify the installed component cleanly.

### v1.0.1

- `ComboboxInputGroup` and `ComboboxContent` now expose independent `data-size` scopes and resolve
omitted sizes to `md`. No prop migration is required.

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