# Combobox Primitive

Combobox is a Starwind Runtime primitive in the floating-value-control contract family.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## Anatomy
### Astro
Use the Astro primitive adapter to render Combobox anatomy with the Runtime wiring included.
```astro
---
import { Combobox } from "@starwind-ui/astro/combobox";
---

<Combobox.Root>
  <Combobox.Label>Choose a framework</Combobox.Label>
  <Combobox.InputGroup>
    <Combobox.Input placeholder="Search frameworks" />
    <Combobox.Trigger>Open</Combobox.Trigger>
    <Combobox.Clear>Clear</Combobox.Clear>
  </Combobox.InputGroup>
  <Combobox.Positioner>
    <Combobox.Popup>
      <Combobox.Empty>No results</Combobox.Empty>
    </Combobox.Popup>
  </Combobox.Positioner>
</Combobox.Root>
```

### React
Use the React primitive adapter when Combobox state participates in React rendering.
```tsx
import { Combobox } from "@starwind-ui/react/combobox";

export function Example() {
  return (
    <Combobox.Root>
      <Combobox.Label>Choose a framework</Combobox.Label>
      <Combobox.InputGroup>
        <Combobox.Input placeholder="Search frameworks" />
        <Combobox.Trigger>Open</Combobox.Trigger>
        <Combobox.Clear>Clear</Combobox.Clear>
      </Combobox.InputGroup>
      <Combobox.Positioner>
        <Combobox.Popup>
          <Combobox.Empty>No results</Combobox.Empty>
        </Combobox.Popup>
      </Combobox.Positioner>
    </Combobox.Root>
  );
}
```

### HTML
Render the Combobox data-sw-* contract yourself, then initialize createCombobox.
```html
<div data-sw-combobox>
  <div data-sw-combobox-label>Choose a framework</div>
  <div data-sw-combobox-input-group>
    <input data-sw-combobox-input role="combobox" aria-autocomplete="list" autocomplete="off" placeholder="Search frameworks" />
    <button data-sw-combobox-trigger aria-haspopup="listbox">Open</button>
    <button data-sw-combobox-clear type="button">Clear</button>
  </div>
  <div data-sw-combobox-positioner>
    <div data-sw-combobox-popup role="listbox" hidden tabindex="-1">
      <div data-sw-combobox-empty hidden>No results</div>
      <div data-sw-combobox-list>
        <div data-sw-combobox-item role="option" data-value="astro">
          <span data-sw-combobox-item-text>Astro</span>
          <span data-sw-combobox-item-indicator aria-hidden="true" hidden></span>
        </div>
      </div>
    </div>
  </div>
</div>

<script type="module">
  import { createCombobox } from "@starwind-ui/runtime/combobox";

  const root = document.querySelector("[data-sw-combobox]");
  if (root) {
    createCombobox(root);
  }
</script>
```

### Vue
Use the Vue 3.5 beta adapter to render Combobox anatomy.
```vue
<script setup lang="ts">
import Combobox from "@starwind-ui/vue/combobox";
</script>

<template>
  <Combobox.Root>
    <Combobox.Label>Choose a framework</Combobox.Label>
    <Combobox.InputGroup>
      <Combobox.Input placeholder="Search frameworks" />
      <Combobox.Trigger>Open</Combobox.Trigger>
      <Combobox.Clear>Clear</Combobox.Clear>
    </Combobox.InputGroup>
    <Combobox.Positioner>
      <Combobox.Popup>
        <Combobox.Empty>No results</Combobox.Empty>
      </Combobox.Popup>
    </Combobox.Positioner>
  </Combobox.Root>
</template>
```
## Floating Behavior
| Fact | Value |
| --- | --- |
| Anchor part | inputGroup |
| Positioner part | positioner |
| Popup part | popup |
| Portal part | portal |
| Option props | side, align, sideOffset, alignOffset, avoidCollisions |
## API Reference
### Root
The main element that owns the Combobox Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-combobox` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| open | `boolean` | - | control | Controls whether Combobox is open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
| defaultOpen | `boolean` | - | control | Sets whether Combobox starts open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
| value | `string \| null` | - | control | Controls the current Combobox value. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
| defaultValue | `string \| null` | - | control | Sets the initial Combobox value for uncontrolled usage. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
| inputValue | `string` | - | control | Controls the input value for Combobox. | **React:** Use inputValue for controlled state and defaultInputValue for default state, and onInputValueChange for change proposals.<br>**Astro:** Use inputValue or defaultInputValue for initial state, listen for starwind:input-value-change, and call setInputValue for later updates.<br>**Runtime / HTML:** Use data-default-input-value for initial state, listen for starwind:input-value-change, and call setInputValue for later updates. |
| defaultInputValue | `string` | - | control | Controls the default input value for Combobox. | **React:** Use inputValue for controlled state and defaultInputValue for default state, and onInputValueChange for change proposals.<br>**Astro:** Use inputValue or defaultInputValue for initial state, listen for starwind:input-value-change, and call setInputValue for later updates.<br>**Runtime / HTML:** Use data-default-input-value for initial state, listen for starwind:input-value-change, and call setInputValue for later updates. |
| autoComplete | `string` | - | option | Sets the native autocomplete behavior. | - |
| disabled | `boolean` | - | option | Disables the Root part. | - |
| filterMode | `"contains" \| "startsWith"` | "contains" | option | Configures the filter mode option for the Root part. | - |
| form | `string` | - | option | Associates the control with a form element. | - |
| highlightItemOnHover | `boolean` | true | option | Highlights Combobox items when the pointer moves over them. | - |
| locale | `string` | - | option | Sets the locale used by Combobox. | - |
| modal | `boolean` | false | option | Makes Combobox behave as a modal overlay. | - |
| name | `string` | - | option | Sets the submitted form field name. | - |
| readOnly | `boolean` | false | option | Marks the control as read-only. | - |
| required | `boolean` | - | option | Marks the form control as required. | - |
| onInputValueChange | `(inputValue: string, details: ComboboxInputValueChangeDetails) => void` | - | callback | Runs when on input value change changes for Combobox. | **React:** Use inputValue for controlled state and defaultInputValue for default state, and onInputValueChange for change proposals.<br>**Astro:** Use inputValue or defaultInputValue for initial state, listen for starwind:input-value-change, and call setInputValue for later updates.<br>**Runtime / HTML:** Use data-default-input-value for initial state, listen for starwind:input-value-change, and call setInputValue for later updates. |
| onOpenChange | `(open: boolean, details: ComboboxOpenChangeDetails) => void` | - | callback | Runs when Combobox opens or closes. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
| onValueChange | `(value: string \| null, details: ComboboxValueChangeDetails) => void` | - | callback | Runs when the Combobox value changes. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-combobox` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Root part. |
| `data-autocomplete` | prop | - | Reflects the autocomplete prop on the Root part. |
| `data-default-input-value` | prop | - | Reflects the default input value prop on the Root part. |
| `data-default-open` | prop | - | Reflects the default open prop on the Root part. |
| `data-default-value` | prop | - | Reflects the default value prop on the Root part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Root part. |
| `data-filter-mode` | prop | - | Reflects the filter mode prop on the Root part. |
| `data-form` | prop | - | Reflects the form prop on the Root part. |
| `data-highlight-item-on-hover` | prop | - | Reflects the highlight item on hover prop on the Root part. |
| `data-input-value` | state | - | Reflects the input value state on the Root part. |
| `data-locale` | prop | - | Reflects the locale prop on the Root part. |
| `data-modal` | prop | - | Reflects the modal prop on the Root part. |
| `data-name` | prop | - | Reflects the name prop on the Root part. |
| `data-readonly` | prop | - | Reflects the readonly prop on the Root part. |
| `data-required` | prop | - | Reflects the required prop on the Root part. |
#### State
| State | Value Type | Controlled Prop | Default Prop | Initial Attribute | Runtime Getter | Runtime Setter | Description | State Control Support |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| inputValue | `string` | inputValue | defaultInputValue | `data-default-input-value` | `getInputValue` | `setInputValue` | Tracks the current text input value for Combobox. | **React:** Use inputValue for controlled state and defaultInputValue for default state, and onInputValueChange for change proposals.<br>**Astro:** Use inputValue or defaultInputValue for initial state, listen for starwind:input-value-change, and call setInputValue for later updates.<br>**Runtime / HTML:** Use data-default-input-value for initial state, listen for starwind:input-value-change, and call setInputValue for later updates. |
| open | `boolean` | open | defaultOpen | `data-default-open` | `getOpen` | `setOpen` | Tracks whether Combobox is open. | **React:** Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.<br>**Astro:** Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.<br>**Runtime / HTML:** Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates. |
| value | `string \| null` | value | defaultValue | `data-default-value` | `getValue` | `setValue` | Tracks the current Combobox value. | **React:** Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.<br>**Astro:** Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.<br>**Runtime / HTML:** Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description | Cancellation Sequence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| inputValueChange | onInputValueChange | starwind:input-value-change | inputValue: `string` | ComboboxInputValueChangeDetails | before-state-commit | Yes | Fires when the text input value changes for Combobox. | 1. Check internal eligibility and intent.<br>2. Create one details object for the proposal.<br>3. Call the Runtime callback with the details object when the controller exposes one.<br>4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.<br>5. Read details.isCanceled, including cancellation caused by preventDefault().<br>6. Apply the accepted state.<br>7. Notify Runtime subscribers and other accepted-only observers. |
| openChange | onOpenChange | starwind:open-change | open: `boolean` | ComboboxOpenChangeDetails | before-state-commit | Yes | Fires when Combobox opens or closes. | 1. Check internal eligibility and intent.<br>2. Create one details object for the proposal.<br>3. Call the Runtime callback with the details object when the controller exposes one.<br>4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.<br>5. Read details.isCanceled, including cancellation caused by preventDefault().<br>6. Apply the accepted state.<br>7. Notify Runtime subscribers and other accepted-only observers. |
| valueChange | onValueChange | starwind:value-change | value: `string \| null` | ComboboxValueChangeDetails | before-state-commit | Yes | Fires when the value changes for Combobox. | 1. Check internal eligibility and intent.<br>2. Create one details object for the proposal.<br>3. Call the Runtime callback with the details object when the controller exposes one.<br>4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.<br>5. Read details.isCanceled, including cancellation caused by preventDefault().<br>6. Apply the accepted state.<br>7. Notify Runtime subscribers and other accepted-only observers. |
#### Runtime Setters
| Method | Target | Options | Suppresses Emit | Description |
| --- | --- | --- | --- | --- |
| `setDisabled` | prop: disabled | - | No | Updates whether Combobox is disabled from Runtime code. |
| `setInputValue` | state: inputValue | emit: false, filter: false | Yes | Updates the Combobox text input value from Runtime code. |
| `setOpen` | state: open | - | Yes | Opens or closes Combobox from Runtime code. |
| `setValue` | state: value | - | Yes | Updates the current Combobox value from Runtime code. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Form
| Fact | Value |
| --- | --- |
| Form props | autoComplete, form, name, required, value |
| Hidden input | hiddenInput (hidden) |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | No |
| Unmount policy | runtime-owned |
| Keep mounted prop | - |

### Label
Text label associated with Combobox.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-combobox-label` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-combobox-label` | runtime | - | Marks the Label part so Starwind Runtime can find it. |

### Input Group
Groups the input controls for Combobox.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-combobox-input-group` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-combobox-input-group` | runtime | - | Marks the Input Group part so Starwind Runtime can find it. |

### Input
The native input synchronized by Combobox.
| Fact | Value |
| --- | --- |
| Default element | `input` |
| Discovery hook | `data-sw-combobox-input` |
| Role | `combobox` |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-combobox-input` | runtime | - | Marks the Input part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| input | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `role`, `aria-autocomplete`, `aria-controls`, `aria-expanded`, `autocomplete` | Editable combobox semantics must be available before hydration. |

### Trigger
The control that opens, closes, or targets the Combobox content.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-combobox-trigger` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| asChild | `boolean` | - | rendering | Merges behavior onto your child element instead of rendering the default Trigger element. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-combobox-trigger` | runtime | - | Marks the Trigger part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Trigger part. |
#### Refs
| Part | Public |
| --- | --- |
| trigger | Yes |
#### asChild
| Part | Merged Props |
| --- | --- |
| trigger | aria, className, data, ref |

### Icon
Decorative icon rendered by Combobox.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-combobox-icon` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-combobox-icon` | runtime | - | Marks the Icon part so Starwind Runtime can find it. |

### Clear
Clears the current Combobox value.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-combobox-clear` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| asChild | `boolean` | - | rendering | Merges behavior onto your child element instead of rendering the default Clear element. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-combobox-clear` | runtime | - | Marks the Clear part so Starwind Runtime can find it. |
#### asChild
| Part | Merged Props |
| --- | --- |
| clear | aria, className, data, events, ref |

### Value
Displays the current Combobox value.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-combobox-value` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-combobox-value` | runtime | - | Marks the Value part so Starwind Runtime can find it. |

### Hidden Input
The hidden native input synchronized by Combobox.
| Fact | Value |
| --- | --- |
| Default element | `input` |
| Discovery hook | `data-sw-combobox-hidden-input` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-combobox-hidden-input` | runtime | - | Marks the Hidden Input part so Starwind Runtime can find it. |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `type`, `form`, `name`, `value`, `aria-hidden`, `tabIndex` | Form value submission must work without waiting for the runtime. |
#### Form
| Fact | Value |
| --- | --- |
| Form props | autoComplete, form, name, required, value |
| Hidden input | hiddenInput (hidden) |

### Portal
Moves Combobox overlay content to the document body when needed.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-combobox-portal` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-combobox-portal` | runtime | - | Marks the Portal part so Starwind Runtime can find it. |
| `data-container` | prop | - | Reflects the container prop on the Portal part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Portal part. |
| `data-sw-portal-placement` | constant | `runtime` | Identifies Portal metadata for styling and selectors. |
| `data-placement` | runtime | - | Marks the Portal part so Starwind Runtime can find it. |

### Positioner
Positions the Combobox content relative to its trigger.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-combobox-positioner` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| side | `"top" \| "right" \| "bottom" \| "left"` | "bottom" | option | Sets the preferred side for Combobox content. | - |
| align | `"start" \| "center" \| "end"` | "start" | option | Sets how Combobox content aligns to its trigger. | - |
| sideOffset | `number` | 4 | option | Sets the distance between Combobox content and its trigger. | - |
| alignOffset | `number` | 0 | option | Adjusts the cross-axis alignment offset for Combobox content. | - |
| avoidCollisions | `boolean` | true | option | Allows Combobox content to shift or flip to stay visible. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-combobox-positioner` | runtime | - | Marks the Positioner part so Starwind Runtime can find it. |
| `data-side` | prop | - | Reflects the side prop on the Positioner part. |
| `data-align` | prop | - | Reflects the align prop on the Positioner part. |
| `data-side-offset` | prop | - | Reflects the side offset prop on the Positioner part. |
| `data-align-offset` | prop | - | Reflects the align offset prop on the Positioner part. |
| `data-avoid-collisions` | prop | - | Reflects the avoid collisions prop on the Positioner part. |

### Popup
The floating content container for Combobox.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-combobox-popup` |
| Role | `listbox` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| side | `"top" \| "right" \| "bottom" \| "left"` | "bottom" | option | Sets the preferred side for Combobox content. | - |
| align | `"start" \| "center" \| "end"` | "start" | option | Sets how Combobox content aligns to its trigger. | - |
| sideOffset | `number` | 4 | option | Sets the distance between Combobox content and its trigger. | - |
| alignOffset | `number` | 0 | option | Adjusts the cross-axis alignment offset for Combobox content. | - |
| avoidCollisions | `boolean` | true | option | Allows Combobox content to shift or flip to stay visible. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-combobox-popup` | runtime | - | Marks the Popup part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Popup part. |
| `data-side` | prop | - | Reflects the side prop on the Popup part. |
| `data-align` | prop | - | Reflects the align prop on the Popup part. |
| `data-side-offset` | prop | - | Reflects the side offset prop on the Popup part. |
| `data-align-offset` | prop | - | Reflects the align offset prop on the Popup part. |
| `data-avoid-collisions` | prop | - | Reflects the avoid collisions prop on the Popup part. |
#### Refs
| Part | Public |
| --- | --- |
| popup | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `role`, `hidden`, `data-state`, `data-side`, `data-align` | Floating content starts closed and is positioned by the runtime once opened. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | Yes |
| Unmount policy | runtime-owned |
| Keep mounted prop | - |

### Empty
Content shown when Combobox has no matching items.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-combobox-empty` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-combobox-empty` | runtime | - | Marks the Empty part so Starwind Runtime can find it. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | Yes |
| Unmount policy | runtime-owned |
| Keep mounted prop | - |

### List
The list of selectable Combobox items.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-combobox-list` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-combobox-list` | runtime | - | Marks the List part so Starwind Runtime can find it. |

### Group
Groups related Combobox items.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-combobox-group` |
| Role | `group` |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-combobox-group` | runtime | - | Marks the Group part so Starwind Runtime can find it. |

### Group Label
Labels a group of Combobox items.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-combobox-group-label` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-combobox-group-label` | runtime | - | Marks the Group Label part so Starwind Runtime can find it. |

### Item
An interactive item inside the Combobox collection.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-combobox-item` |
| Role | `option` |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-combobox-item` | runtime | - | Marks the Item part so Starwind Runtime can find it. |
| `data-value` | prop | - | Reflects the value prop on the Item part. |
| `data-disabled` | prop | - | Reflects the disabled prop on the Item part. |
#### Refs
| Part | Public |
| --- | --- |
| item | Yes |

### Item Text
Text content for a Combobox item.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-combobox-item-text` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-combobox-item-text` | runtime | - | Marks the Item Text part so Starwind Runtime can find it. |

### Item Indicator
Shows the selected state for a Combobox item.
| Fact | Value |
| --- | --- |
| Default element | `span` |
| Discovery hook | `data-sw-combobox-item-indicator` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-combobox-item-indicator` | runtime | - | Marks the Item Indicator part so Starwind Runtime can find it. |
| `data-state` | state | - | Reflects the current state on the Item Indicator part. |
| `data-hidden` | state | - | Reflects the hidden state on the Item Indicator part. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | Yes |
| Unmount policy | runtime-owned |
| Keep mounted prop | - |

### Separator
Separates groups of Combobox items.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-combobox-separator` |
| Role | `separator` |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-combobox-separator` | runtime | - | Marks the Separator part so Starwind Runtime can find it. |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createCombobox`](/docs/runtime/#create-combobox) |
| Import | `@starwind-ui/runtime/combobox` |
| Root part | root |
| Option props | autoComplete, defaultInputValue, defaultOpen, defaultValue, disabled, filterMode, form, highlightItemOnHover, inputValue, locale, modal, name, open, readOnly, required, value |
| Option lifecycles | autoComplete: setter-backed, defaultInputValue: constructor-only, defaultOpen: constructor-only, defaultValue: constructor-only, disabled: setter-backed, filterMode: constructor-only, form: setter-backed, highlightItemOnHover: constructor-only, inputValue: setter-backed, locale: constructor-only, modal: constructor-only, name: setter-backed, open: setter-backed, readOnly: constructor-only, required: setter-backed, value: setter-backed |
## Form Participation
| Fact | Value |
| --- | --- |
| Form props | autoComplete, form, name, required, value |
| Hidden input | hiddenInput (hidden) |
| Field integration | Yes |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Combobox](/docs/components/combobox/) | Direct Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/combobox` | `createCombobox` |
| Astro Primitive | `@starwind-ui/astro/combobox` | `Combobox`, `ComboboxRoot`, `ComboboxLabel`, `ComboboxInputGroup`, `ComboboxInput`, `ComboboxTrigger`, `ComboboxIcon`, `ComboboxClear`, `ComboboxValue`, `ComboboxPortal`, `ComboboxPositioner`, `ComboboxPopup`, `ComboboxEmpty`, `ComboboxGroup`, `ComboboxGroupLabel`, `ComboboxItem`, `ComboboxItemText`, `ComboboxItemIndicator`, `ComboboxSeparator` |
| React Primitive | `@starwind-ui/react/combobox` | `Combobox`, `ComboboxRoot`, `ComboboxLabel`, `ComboboxInputGroup`, `ComboboxInput`, `ComboboxTrigger`, `ComboboxIcon`, `ComboboxClear`, `ComboboxValue`, `ComboboxPortal`, `ComboboxPositioner`, `ComboboxPopup`, `ComboboxEmpty`, `ComboboxGroup`, `ComboboxGroupLabel`, `ComboboxItem`, `ComboboxItemText`, `ComboboxItemIndicator`, `ComboboxSeparator` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `Combobox` |
| runtime-factory | `createCombobox` |
| part | `Combobox.Root` |
| part | `Combobox.Label` |
| part | `Combobox.InputGroup` |
| part | `Combobox.Input` |
| part | `Combobox.Trigger` |
| part | `Combobox.Icon` |
| part | `Combobox.Clear` |
| part | `Combobox.Value` |
| part | `Combobox.Portal` |
| part | `Combobox.Positioner` |
| part | `Combobox.Popup` |
| part | `Combobox.Empty` |
| part | `Combobox.Group` |
| part | `Combobox.GroupLabel` |
| part | `Combobox.Item` |
| part | `Combobox.ItemText` |
| part | `Combobox.ItemIndicator` |
| part | `Combobox.Separator` |
## Changelog
### v1.1.1
- Connected owned group headings to their groups with aria-labelledby so assistive technology can identify each group.
### v1.1.0
- Added portable Portal container and disabled controls, with deterministic framework and Runtime placement reporting for nested floating content.
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.2
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
- Kept generated React state-change callbacks and DOM events cancelable until the Runtime accepts the proposed state, then synchronized rendered state.
- Preserved cancellation for React Combobox value and input commands.
### v0.1.1
- Added modal background-scroll locking while the combobox popup is open.
### v0.1.0
- Introduced filtering, selection, keyboard navigation, floating-list placement, and form participation.