Combobox Primitive

Combobox is a Starwind Runtime primitive in the floating-value-control contract family.

Anatomy

Use the Astro primitive adapter to render Combobox anatomy with the Runtime wiring included.

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

Use the React primitive adapter when Combobox state participates in React rendering.

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>
  );
}

Render the Combobox data-sw-* contract yourself, then initialize createCombobox.

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

Default element: div
Discovery hook: data-sw-combobox
Role: -

Props

Prop Type Default

open boolean -

Description: Controls whether Combobox is open.
Kind: control
Targets: -
Full type: boolean

defaultOpen boolean -

Description: Sets whether Combobox starts open.
Kind: control
Targets: -
Full type: boolean

value string | null -

Description: Controls the current Combobox value.
Kind: control
Targets: -
Full type: string | null

defaultValue string | null -

Description: Sets the initial Combobox value for uncontrolled usage.
Kind: control
Targets: -
Full type: string | null

inputValue string -

Description: Controls the input value for Combobox.
Kind: control
Targets: -
Full type: string

defaultInputValue string -

Description: Controls the default input value for Combobox.
Kind: control
Targets: -
Full type: string

autoComplete string -

Description: Sets the native autocomplete behavior.
Kind: option
Targets: -
Full type: string

disabled boolean -

Description: Disables the Root part.
Kind: option
Targets: -
Full type: boolean

filterMode "contains" | "startsWith" "contains"

Description: Configures the filter mode option for the Root part.
Kind: option
Targets: -
Full type: "contains" | "startsWith"

form string -

Description: Associates the control with a form element.
Kind: option
Targets: -
Full type: string

highlightItemOnHover boolean true

Description: Highlights Combobox items when the pointer moves over them.
Kind: option
Targets: -
Full type: boolean

locale string -

Description: Sets the locale used by Combobox.
Kind: option
Targets: -
Full type: string

modal boolean false

Description: Makes Combobox behave as a modal overlay.
Kind: option
Targets: -
Full type: boolean

name string -

Description: Sets the submitted form field name.
Kind: option
Targets: -
Full type: string

readOnly boolean false

Description: Marks the control as read-only.
Kind: option
Targets: -
Full type: boolean

required boolean -

Description: Marks the form control as required.
Kind: option
Targets: -
Full type: boolean

onInputValueChange (inputValue: string, details: ComboboxInputValueChangeDetails) => void -

Description: Runs when on input value change changes for Combobox.
Kind: callback
Targets: -
Full type: (inputValue: string, details: ComboboxInputValueChangeDetails) => void

onOpenChange (open: boolean, details: ComboboxOpenChangeDetails) => void -

Description: Runs when Combobox opens or closes.
Kind: callback
Targets: -
Full type: (open: boolean, details: ComboboxOpenChangeDetails) => void

onValueChange (value: string | null, details: ComboboxValueChangeDetails) => void -

Description: Runs when the Combobox value changes.
Kind: callback
Targets: -
Full type: (value: string | null, details: ComboboxValueChangeDetails) => void

Events

Event Callback Value

inputValueChange onInputValueChange inputValue: string

Description: Fires when the text input value changes for Combobox.
DOM event: starwind:input-value-change
Details type: ComboboxInputValueChangeDetails
Timing: -
Cancelable: Yes

openChange onOpenChange open: boolean

Description: Fires when Combobox opens or closes.
DOM event: starwind:open-change
Details type: ComboboxOpenChangeDetails
Timing: -
Cancelable: Yes

valueChange onValueChange value: string | null

Description: Fires when the value changes for Combobox.
DOM event: starwind:value-change
Details type: ComboboxValueChangeDetails
Timing: -
Cancelable: Yes

State

State Type Props

inputValue string inputValue / defaultInputValue

Description: Tracks the current text input value for Combobox.
Initial attribute: data-default-input-value
Runtime getter: getInputValue
Runtime setter: setInputValue
State control support: 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

Description: Tracks whether Combobox is open.
Initial attribute: data-default-open
Runtime getter: getOpen
Runtime setter: setOpen
State control support: 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

Description: Tracks the current Combobox value.
Initial attribute: data-default-value
Runtime getter: getValue
Runtime setter: setValue
State control support: 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.

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-combobox - Marks the Root part so Starwind Runtime can find it.

State

Attribute Value Description

data-state - Reflects the current state on the Root part.

data-input-value - Reflects the input value state on the Root part.

Metadata

Attribute Value Description

data-autocomplete - Reflects the autocomplete prop on the Root part.

data-default-input-value - Reflects the default input value prop on the Root part.

data-default-open - Reflects the default open prop on the Root part.

data-default-value - Reflects the default value prop on the Root part.

data-disabled - Reflects the disabled prop on the Root part.

data-filter-mode - Reflects the filter mode prop on the Root part.

data-form - Reflects the form prop on the Root part.

data-highlight-item-on-hover - Reflects the highlight item on hover prop on the Root part.

data-locale - Reflects the locale prop on the Root part.

data-modal - Reflects the modal prop on the Root part.

data-name - Reflects the name prop on the Root part.

data-readonly - Reflects the readonly prop on the Root part.

data-required - Reflects the required prop on the Root part.

Label

Text label associated with Combobox.

Default element: div
Discovery hook: data-sw-combobox-label
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-combobox-label - Marks the Label part so Starwind Runtime can find it.

Input Group

Groups the input controls for Combobox.

Default element: div
Discovery hook: data-sw-combobox-input-group
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-combobox-input-group - Marks the Input Group part so Starwind Runtime can find it.

Input

The native input synchronized by Combobox.

Default element: input
Discovery hook: data-sw-combobox-input
Role: combobox

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-combobox-input - Marks the Input part so Starwind Runtime can find it.

Trigger

The control that opens, closes, or targets the Combobox content.

Default element: button
Discovery hook: data-sw-combobox-trigger
Role: -

Props

Prop Type Default

asChild boolean -

Description: Merges behavior onto your child element instead of rendering the default Trigger element.
Kind: rendering
Targets: clear, trigger
Full type: boolean

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-combobox-trigger - Marks the Trigger part so Starwind Runtime can find it.

State

Attribute Value Description

data-state - Reflects the current state on the Trigger part.

Icon

Decorative icon rendered by Combobox.

Default element: span
Discovery hook: data-sw-combobox-icon
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-combobox-icon - Marks the Icon part so Starwind Runtime can find it.

Clear

Clears the current Combobox value.

Default element: button
Discovery hook: data-sw-combobox-clear
Role: -

Props

Prop Type Default

asChild boolean -

Description: Merges behavior onto your child element instead of rendering the default Clear element.
Kind: rendering
Targets: clear, trigger
Full type: boolean

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-combobox-clear - Marks the Clear part so Starwind Runtime can find it.

Value

Displays the current Combobox value.

Default element: span
Discovery hook: data-sw-combobox-value
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-combobox-value - Marks the Value part so Starwind Runtime can find it.

Hidden Input

The hidden native input synchronized by Combobox.

Default element: input
Discovery hook: data-sw-combobox-hidden-input
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-combobox-hidden-input - Marks the Hidden Input part so Starwind Runtime can find it.

Portal

Moves Combobox overlay content to the document body when needed.

Default element: div
Discovery hook: data-sw-combobox-portal
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-combobox-portal - Marks the Portal part so Starwind Runtime can find it.

Positioner

Positions the Combobox content relative to its trigger.

Default element: div
Discovery hook: data-sw-combobox-positioner
Role: -

Props

Prop Type Default

side "top" | "right" | "bottom" | "left" "bottom"

Description: Sets the preferred side for Combobox content.
Kind: option
Targets: positioner, popup
Full type: "top" | "right" | "bottom" | "left"

align "start" | "center" | "end" "start"

Description: Sets how Combobox content aligns to its trigger.
Kind: option
Targets: positioner, popup
Full type: "start" | "center" | "end"

sideOffset number 4

Description: Sets the distance between Combobox content and its trigger.
Kind: option
Targets: positioner, popup
Full type: number

alignOffset number 0

Description: Adjusts the cross-axis alignment offset for Combobox content.
Kind: option
Targets: positioner, popup
Full type: number

avoidCollisions boolean true

Description: Allows Combobox content to shift or flip to stay visible.
Kind: option
Targets: positioner, popup
Full type: boolean

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-combobox-positioner - Marks the Positioner part so Starwind Runtime can find it.

Metadata

Attribute Value Description

data-side - Reflects the side prop on the Positioner part.

data-align - Reflects the align prop on the Positioner part.

data-side-offset - Reflects the side offset prop on the Positioner part.

data-align-offset - Reflects the align offset prop on the Positioner part.

data-avoid-collisions - Reflects the avoid collisions prop on the Positioner part.

The floating content container for Combobox.

Default element: div
Discovery hook: data-sw-combobox-popup
Role: listbox

Props

Prop Type Default

side "top" | "right" | "bottom" | "left" "bottom"

Description: Sets the preferred side for Combobox content.
Kind: option
Targets: positioner, popup
Full type: "top" | "right" | "bottom" | "left"

align "start" | "center" | "end" "start"

Description: Sets how Combobox content aligns to its trigger.
Kind: option
Targets: positioner, popup
Full type: "start" | "center" | "end"

sideOffset number 4

Description: Sets the distance between Combobox content and its trigger.
Kind: option
Targets: positioner, popup
Full type: number

alignOffset number 0

Description: Adjusts the cross-axis alignment offset for Combobox content.
Kind: option
Targets: positioner, popup
Full type: number

avoidCollisions boolean true

Description: Allows Combobox content to shift or flip to stay visible.
Kind: option
Targets: positioner, popup
Full type: boolean

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-combobox-popup - Marks the Popup part so Starwind Runtime can find it.

State

Attribute Value Description

data-state - Reflects the current state on the Popup part.

Metadata

Attribute Value Description

data-side - Reflects the side prop on the Popup part.

data-align - Reflects the align prop on the Popup part.

data-side-offset - Reflects the side offset prop on the Popup part.

data-align-offset - Reflects the align offset prop on the Popup part.

data-avoid-collisions - Reflects the avoid collisions prop on the Popup part.

Empty

Content shown when Combobox has no matching items.

Default element: div
Discovery hook: data-sw-combobox-empty
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-combobox-empty - Marks the Empty part so Starwind Runtime can find it.

List

The list of selectable Combobox items.

Default element: div
Discovery hook: data-sw-combobox-list
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-combobox-list - Marks the List part so Starwind Runtime can find it.

Group

Groups related Combobox items.

Default element: div
Discovery hook: data-sw-combobox-group
Role: group

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-combobox-group - Marks the Group part so Starwind Runtime can find it.

Group Label

Labels a group of Combobox items.

Default element: div
Discovery hook: data-sw-combobox-group-label
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-combobox-group-label - Marks the Group Label part so Starwind Runtime can find it.

Item

An interactive item inside the Combobox collection.

Default element: div
Discovery hook: data-sw-combobox-item
Role: option

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-combobox-item - Marks the Item part so Starwind Runtime can find it.

Metadata

Attribute Value Description

data-value - Reflects the value prop on the Item part.

data-disabled - Reflects the disabled prop on the Item part.

Item Text

Text content for a Combobox item.

Default element: span
Discovery hook: data-sw-combobox-item-text
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-combobox-item-text - Marks the Item Text part so Starwind Runtime can find it.

Item Indicator

Shows the selected state for a Combobox item.

Default element: span
Discovery hook: data-sw-combobox-item-indicator
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-combobox-item-indicator - Marks the Item Indicator part so Starwind Runtime can find it.

State

Attribute Value Description

data-state - Reflects the current state on the Item Indicator part.

data-hidden - Reflects the hidden state on the Item Indicator part.

Separator

Separates groups of Combobox items.

Default element: div
Discovery hook: data-sw-combobox-separator
Role: separator

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-combobox-separator - Marks the Separator part so Starwind Runtime can find it.

Runtime API

Factory: createCombobox
Import: @starwind-ui/runtime/combobox
Root hook: root data-sw-combobox
Option props: autoComplete, defaultInputValue, defaultOpen, defaultValue, disabled, filterMode, form, highlightItemOnHover, inputValue, locale, modal, name, open, readOnly, required, value

Option Lifecycles

Option	Lifecycle
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

Runtime Setters

Method Target Description

setDisabled prop: disabled Updates whether Combobox is disabled from Runtime code.

setInputValue state: inputValue Updates the Combobox text input value from Runtime code.

setOpen state: open Opens or closes Combobox from Runtime code.

setValue state: value Updates the current Combobox value from Runtime code.

Form Participation

Fact	Value
Form props	autoComplete, form, name, required, value
Hidden input	hiddenInput (hidden)
Field integration	Yes

Component Relationship

Combobox Direct primitive

Layer Metadata

Combobox Primitive uses createCombobox. Styled components: Combobox.

primitive Combobox Primitive Combobox Primitive uses createCombobox. Styled components: Combobox. Runtime primitive Primitive adapter Astro Primitive adapters React Primitive adapters combobox Combobox Floating Value Control Value controls with popup selection surfaces and floating placement. /docs/primitives/combobox/ createCombobox @starwind-ui/runtime/combobox /docs/runtime/#create-combobox root autoComplete defaultInputValue defaultOpen defaultValue disabled filterMode form highlightItemOnHover inputValue locale modal name open readOnly required value raw-html astro react solid svelte vue HTML Astro React Solid Svelte Vue Raw HTML Render the Combobox data-sw-* contract yourself, then initialize createCombobox. html Use the Astro primitive adapter to render Combobox anatomy with the Runtime wiring included. Use the React primitive adapter when Combobox state participates in React rendering. tsx div data-sw-combobox boolean Controls whether Combobox is open. Sets whether Combobox starts open. string | null Controls the current Combobox value. Sets the initial Combobox value for uncontrolled usage. string Controls the input value for Combobox. Controls the default input value for Combobox. Sets the native autocomplete behavior. Disables the Root part. "contains" | "startsWith" Configures the filter mode option for the Root part. Associates the control with a form element. Highlights Combobox items when the pointer moves over them. Sets the locale used by Combobox. Makes Combobox behave as a modal overlay. Sets the submitted form field name. Marks the control as read-only. Marks the form control as required. onInputValueChange (inputValue: string, details: ComboboxInputValueChangeDetails) => void ComboboxInputValueChangeDetails Runs when on input value change changes for Combobox. onOpenChange (open: boolean, details: ComboboxOpenChangeDetails) => void ComboboxOpenChangeDetails Runs when Combobox opens or closes. onValueChange (value: string | null, details: ComboboxValueChangeDetails) => void ComboboxValueChangeDetails Runs when the Combobox value changes. 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 Reflects the default input value prop on the Root part. data-default-open Reflects the default open prop on the Root part. data-default-value Reflects the default value prop on the Root part. data-disabled Reflects the disabled prop on the Root part. data-filter-mode Reflects the filter mode prop on the Root part. data-form Reflects the form prop on the Root part. data-highlight-item-on-hover Reflects the highlight item on hover prop on the Root part. data-input-value Reflects the input value state on the Root part. data-locale Reflects the locale prop on the Root part. data-modal Reflects the modal prop on the Root part. data-name Reflects the name prop on the Root part. data-readonly Reflects the readonly prop on the Root part. data-required Reflects the required prop on the Root part. getInputValue setInputValue getOpen setOpen getValue setValue inputValueChange starwind:input-value-change openChange starwind:open-change valueChange starwind:value-change setDisabled label data-sw-combobox-label Marks the Label part so Starwind Runtime can find it. inputGroup data-sw-combobox-input-group Marks the Input Group part so Starwind Runtime can find it. input data-sw-combobox-input Marks the Input part so Starwind Runtime can find it. trigger button data-sw-combobox-trigger asChild Merges behavior onto your child element instead of rendering the default Trigger element. Marks the Trigger part so Starwind Runtime can find it. Reflects the current state on the Trigger part. icon span data-sw-combobox-icon Marks the Icon part so Starwind Runtime can find it. clear data-sw-combobox-clear Merges behavior onto your child element instead of rendering the default Clear element. Marks the Clear part so Starwind Runtime can find it. data-sw-combobox-value Marks the Value part so Starwind Runtime can find it. hiddenInput data-sw-combobox-hidden-input Marks the Hidden Input part so Starwind Runtime can find it. portal data-sw-combobox-portal Marks the Portal part so Starwind Runtime can find it. positioner data-sw-combobox-positioner side "top" | "right" | "bottom" | "left" Sets the preferred side for Combobox content. align "start" | "center" | "end" Sets how Combobox content aligns to its trigger. sideOffset number Sets the distance between Combobox content and its trigger. alignOffset Adjusts the cross-axis alignment offset for Combobox content. avoidCollisions Allows Combobox content to shift or flip to stay visible. Marks the Positioner part so Starwind Runtime can find it. data-side Reflects the side prop on the Positioner part. data-align Reflects the align prop on the Positioner part. data-side-offset Reflects the side offset prop on the Positioner part. data-align-offset Reflects the align offset prop on the Positioner part. data-avoid-collisions Reflects the avoid collisions prop on the Positioner part. popup data-sw-combobox-popup listbox Marks the Popup part so Starwind Runtime can find it. Reflects the current state on the Popup part. Reflects the side prop on the Popup part. Reflects the align prop on the Popup part. Reflects the side offset prop on the Popup part. Reflects the align offset prop on the Popup part. Reflects the avoid collisions prop on the Popup part. empty data-sw-combobox-empty Marks the Empty part so Starwind Runtime can find it. list data-sw-combobox-list Marks the List part so Starwind Runtime can find it. group data-sw-combobox-group Marks the Group part so Starwind Runtime can find it. groupLabel data-sw-combobox-group-label Marks the Group Label part so Starwind Runtime can find it. item data-sw-combobox-item option Marks the Item part so Starwind Runtime can find it. data-value Reflects the value prop on the Item part. Reflects the disabled prop on the Item part. itemText data-sw-combobox-item-text Marks the Item Text part so Starwind Runtime can find it. itemIndicator data-sw-combobox-item-indicator Marks the Item Indicator part so Starwind Runtime can find it. Reflects the current state on the Item Indicator part. data-hidden Reflects the hidden state on the Item Indicator part. separator data-sw-combobox-separator Marks the Separator part so Starwind Runtime can find it. Root Label Input Group Input aria-autocomplete aria-controls aria-expanded autocomplete Trigger aria-haspopup Icon aria-hidden Clear type Value Hidden Input tabIndex Portal Positioner Popup hidden Empty List Group Group Label Item aria-selected aria-disabled Item Text Item Indicator Separator aria-orientation @starwind-ui/astro @starwind-ui/astro/combobox Generate static combobox markup plus self-init; do not promise controlled props. @starwind-ui/react @starwind-ui/react/combobox Bridge inputValue/open/value as separate controlled models and keep callbacks in latest refs. /docs/components/combobox/ Direct primitive direct-primitive Styled component Combobox