Skip to main content

Starwind UI v3.0 is now available! Migration guide

On this page

Combobox Primitive

View Markdown

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

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>

Floating Behavior

FactValue
Anchor partinputGroup
Positioner partpositioner
Popup partpopup
Portal partportal
Option propsside, 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 Toggle
open boolean -
Description
Controls whether Combobox is open.
Kind
control
Targets
-
Full type
boolean
React

Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.

  • open
  • defaultOpen
  • onOpenChange
Astro

Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.

  • open
  • defaultOpen
  • starwind:open-change
  • setOpen
Runtime / HTML

Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates.

  • data-default-open
  • starwind:open-change
  • setOpen
defaultOpen boolean -
Description
Sets whether Combobox starts open.
Kind
control
Targets
-
Full type
boolean
React

Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.

  • open
  • defaultOpen
  • onOpenChange
Astro

Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.

  • open
  • defaultOpen
  • starwind:open-change
  • setOpen
Runtime / HTML

Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates.

  • data-default-open
  • starwind:open-change
  • setOpen
value string | null -
Description
Controls the current Combobox value.
Kind
control
Targets
-
Full type
string | null
React

Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.

  • value
  • defaultValue
  • onValueChange
Astro

Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.

  • value
  • defaultValue
  • starwind:value-change
  • setValue
Runtime / HTML

Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates.

  • data-default-value
  • starwind:value-change
  • setValue
defaultValue string | null -
Description
Sets the initial Combobox value for uncontrolled usage.
Kind
control
Targets
-
Full type
string | null
React

Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.

  • value
  • defaultValue
  • onValueChange
Astro

Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.

  • value
  • defaultValue
  • starwind:value-change
  • setValue
Runtime / HTML

Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates.

  • data-default-value
  • starwind:value-change
  • setValue
inputValue string -
Description
Controls the input value for Combobox.
Kind
control
Targets
-
Full type
string
React

Use inputValue for controlled state and defaultInputValue for default state, and onInputValueChange for change proposals.

  • inputValue
  • defaultInputValue
  • onInputValueChange
Astro

Use inputValue or defaultInputValue for initial state, listen for starwind:input-value-change, and call setInputValue for later updates.

  • inputValue
  • defaultInputValue
  • starwind:input-value-change
  • setInputValue
Runtime / HTML

Use data-default-input-value for initial state, listen for starwind:input-value-change, and call setInputValue for later updates.

  • data-default-input-value
  • starwind:input-value-change
  • setInputValue
defaultInputValue string -
Description
Controls the default input value for Combobox.
Kind
control
Targets
-
Full type
string
React

Use inputValue for controlled state and defaultInputValue for default state, and onInputValueChange for change proposals.

  • inputValue
  • defaultInputValue
  • onInputValueChange
Astro

Use inputValue or defaultInputValue for initial state, listen for starwind:input-value-change, and call setInputValue for later updates.

  • inputValue
  • defaultInputValue
  • starwind:input-value-change
  • setInputValue
Runtime / HTML

Use data-default-input-value for initial state, listen for starwind:input-value-change, and call setInputValue for later updates.

  • data-default-input-value
  • starwind:input-value-change
  • setInputValue
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
React

Use inputValue for controlled state and defaultInputValue for default state, and onInputValueChange for change proposals.

  • inputValue
  • defaultInputValue
  • onInputValueChange
Astro

Use inputValue or defaultInputValue for initial state, listen for starwind:input-value-change, and call setInputValue for later updates.

  • inputValue
  • defaultInputValue
  • starwind:input-value-change
  • setInputValue
Runtime / HTML

Use data-default-input-value for initial state, listen for starwind:input-value-change, and call setInputValue for later updates.

  • data-default-input-value
  • starwind:input-value-change
  • setInputValue
onOpenChange (open: boolean, details: ComboboxOpenChangeDetails) => void -
Description
Runs when Combobox opens or closes.
Kind
callback
Targets
-
Full type
(open: boolean, details: ComboboxOpenChangeDetails) => void
React

Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.

  • open
  • defaultOpen
  • onOpenChange
Astro

Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.

  • open
  • defaultOpen
  • starwind:open-change
  • setOpen
Runtime / HTML

Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates.

  • data-default-open
  • starwind:open-change
  • setOpen
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
React

Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.

  • value
  • defaultValue
  • onValueChange
Astro

Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.

  • value
  • defaultValue
  • starwind:value-change
  • setValue
Runtime / HTML

Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates.

  • data-default-value
  • starwind:value-change
  • setValue

Events

Event Callback Value Toggle
inputValueChange onInputValueChange inputValue: string
Description
Fires when the text input value changes for Combobox.
DOM event
starwind:input-value-change
Details type
ComboboxInputValueChangeDetails
Timing
before-state-commit
Cancelable
Yes
Cancellation sequence
  1. Check internal eligibility and intent.
  2. Create one details object for the proposal.
  3. Call the Runtime callback with the details object when the controller exposes one.
  4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.
  5. Read details.isCanceled, including cancellation caused by preventDefault().
  6. Apply the accepted state.
  7. Notify Runtime subscribers and other accepted-only observers.
openChange onOpenChange open: boolean
Description
Fires when Combobox opens or closes.
DOM event
starwind:open-change
Details type
ComboboxOpenChangeDetails
Timing
before-state-commit
Cancelable
Yes
Cancellation sequence
  1. Check internal eligibility and intent.
  2. Create one details object for the proposal.
  3. Call the Runtime callback with the details object when the controller exposes one.
  4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.
  5. Read details.isCanceled, including cancellation caused by preventDefault().
  6. Apply the accepted state.
  7. Notify Runtime subscribers and other accepted-only observers.
valueChange onValueChange value: string | null
Description
Fires when the value changes for Combobox.
DOM event
starwind:value-change
Details type
ComboboxValueChangeDetails
Timing
before-state-commit
Cancelable
Yes
Cancellation sequence
  1. Check internal eligibility and intent.
  2. Create one details object for the proposal.
  3. Call the Runtime callback with the details object when the controller exposes one.
  4. Dispatch the cancelable DOM event with the same details object, including when the callback canceled it.
  5. Read details.isCanceled, including cancellation caused by preventDefault().
  6. Apply the accepted state.
  7. Notify Runtime subscribers and other accepted-only observers.

State

State Type Props Toggle
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
React

Use inputValue for controlled state and defaultInputValue for default state, and onInputValueChange for change proposals.

  • inputValue
  • defaultInputValue
  • onInputValueChange
Astro

Use inputValue or defaultInputValue for initial state, listen for starwind:input-value-change, and call setInputValue for later updates.

  • inputValue
  • defaultInputValue
  • starwind:input-value-change
  • setInputValue
Runtime / HTML

Use data-default-input-value for initial state, listen for starwind:input-value-change, and call setInputValue for later updates.

  • data-default-input-value
  • starwind:input-value-change
  • setInputValue
open boolean open / defaultOpen
Description
Tracks whether Combobox is open.
Initial attribute
data-default-open
Runtime getter
getOpen
Runtime setter
setOpen
React

Use open for controlled state and defaultOpen for default state, and onOpenChange for change proposals.

  • open
  • defaultOpen
  • onOpenChange
Astro

Use open or defaultOpen for initial state, listen for starwind:open-change, and call setOpen for later updates.

  • open
  • defaultOpen
  • starwind:open-change
  • setOpen
Runtime / HTML

Use data-default-open for initial state, listen for starwind:open-change, and call setOpen for later updates.

  • data-default-open
  • starwind:open-change
  • setOpen
value string | null value / defaultValue
Description
Tracks the current Combobox value.
Initial attribute
data-default-value
Runtime getter
getValue
Runtime setter
setValue
React

Use value for controlled state and defaultValue for default state, and onValueChange for change proposals.

  • value
  • defaultValue
  • onValueChange
Astro

Use value or defaultValue for initial state, listen for starwind:value-change, and call setValue for later updates.

  • value
  • defaultValue
  • starwind:value-change
  • setValue
Runtime / HTML

Use data-default-value for initial state, listen for starwind:value-change, and call setValue for later updates.

  • data-default-value
  • starwind:value-change
  • setValue

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

Popup

The floating content container for Combobox.

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

Props

Prop Type Default Toggle
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

OptionLifecycle
autoCompletesetter-backed
defaultInputValueconstructor-only
defaultOpenconstructor-only
defaultValueconstructor-only
disabledsetter-backed
filterModeconstructor-only
formsetter-backed
highlightItemOnHoverconstructor-only
inputValuesetter-backed
localeconstructor-only
modalconstructor-only
namesetter-backed
opensetter-backed
readOnlyconstructor-only
requiredsetter-backed
valuesetter-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

FactValue
Form propsautoComplete, form, name, required, value
Hidden inputhiddenInput (hidden)
Field integrationYes

Related Styled Components

Component Relationship
Combobox Direct primitive

Changelog

View version history v1.0.0 4 releases

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.