# Combobox Primitive

Combobox is a Starwind Runtime primitive in the floating-value-control contract family.
## 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>
```
## 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 |
| --- | --- | --- | --- | --- |
| open | `boolean` | - | control | Controls whether Combobox is open. |
| defaultOpen | `boolean` | - | control | Sets whether Combobox starts open. |
| value | `string \| null` | - | control | Controls the current Combobox value. |
| defaultValue | `string \| null` | - | control | Sets the initial Combobox value for uncontrolled usage. |
| inputValue | `string` | - | control | Controls the input value for Combobox. |
| defaultInputValue | `string` | - | control | Controls the default input value for Combobox. |
| 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. |
| onOpenChange | `(open: boolean, details: ComboboxOpenChangeDetails) => void` | - | callback | Runs when Combobox opens or closes. |
| onValueChange | `(value: string \| null, details: ComboboxValueChangeDetails) => void` | - | callback | Runs when the Combobox value changes. |
#### 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 supports controlled and default state with inputValue and defaultInputValue props. Runtime/HTML reads initial state from data-default-input-value, emits starwind:input-value-change, and updates with setInputValue. Astro adapters render initial/default state, but do not expose reactive controlled-state props for this state. |
| open | `boolean` | open | defaultOpen | `data-default-open` | `getOpen` | `setOpen` | Tracks whether Combobox is open. | React supports controlled and default state with open and defaultOpen props. Runtime/HTML reads initial state from data-default-open, emits starwind:open-change, and updates with setOpen. Astro adapters render initial/default state, but do not expose reactive controlled-state props for this state. |
| value | `string \| null` | value | defaultValue | `data-default-value` | `getValue` | `setValue` | Tracks the current Combobox value. | React supports controlled and default state with value and defaultValue props. Runtime/HTML reads initial state from data-default-value, emits starwind:value-change, and updates with setValue. Astro adapters render initial/default state, but do not expose reactive controlled-state props for this state. |
#### Events
| Event | Callback | DOM Event | Value | Details | Timing | Cancelable | Description |
| --- | --- | --- | --- | --- | --- | --- | --- |
| inputValueChange | onInputValueChange | starwind:input-value-change | inputValue: `string` | ComboboxInputValueChangeDetails | - | Yes | Fires when the text input value changes for Combobox. |
| openChange | onOpenChange | starwind:open-change | open: `boolean` | ComboboxOpenChangeDetails | - | Yes | Fires when Combobox opens or closes. |
| valueChange | onValueChange | starwind:value-change | value: `string \| null` | ComboboxValueChangeDetails | - | Yes | Fires when the value changes for Combobox. |
#### 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 |
| --- | --- | --- | --- | --- |
| 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 |
| --- | --- | --- | --- | --- |
| 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. |

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