On this page

Combobox

Framework

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

<Combobox name="framework" defaultValue="astro" required>
  <ComboboxLabel>Framework</ComboboxLabel>
  <ComboboxInput placeholder="Search frameworks" showClear />
  <ComboboxContent>
    <ComboboxEmpty>No framework found.</ComboboxEmpty>
    <ComboboxItem value="astro">Astro</ComboboxItem>
    <ComboboxItem value="react">React</ComboboxItem>
    <ComboboxItem value="vue">Vue</ComboboxItem>
  </ComboboxContent>
</Combobox>

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

export function Example() {
  return (
    <Combobox name="framework" defaultValue="astro" required>
      <ComboboxLabel>Framework</ComboboxLabel>
      <ComboboxInput placeholder="Search frameworks" showClear />
      <ComboboxContent>
        <ComboboxEmpty>No framework found.</ComboboxEmpty>
        <ComboboxItem value="astro">Astro</ComboboxItem>
        <ComboboxItem value="react">React</ComboboxItem>
        <ComboboxItem value="vue">Vue</ComboboxItem>
      </ComboboxContent>
    </Combobox>
  );
}

Runtime example adjustment

Combobox is now its own CLI-installed Runtime component. Use its input, content, and item parts instead of the removed Select search composition.

Installation

pnpx starwind@latest add combobox

npx starwind@latest add combobox

yarn dlx starwind@latest add combobox

Framework Availability

Astro Available React Available

Combobox is available for Astro and React.

Usage

Filtering and clearing

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

<Combobox filterMode="startsWith" locale="en">
  <ComboboxInput aria-label="Fruit" placeholder="Search fruit" showClear />
  <ComboboxContent>
    <ComboboxEmpty>No fruit found.</ComboboxEmpty>
    <ComboboxItem value="apple">Apple</ComboboxItem>
    <ComboboxItem value="apricot">Apricot</ComboboxItem>
    <ComboboxItem value="banana">Banana</ComboboxItem>
  </ComboboxContent>
</Combobox>

Runtime example adjustment

Filtering, empty state, keyboard navigation, selection, and form serialization are managed by the Combobox Runtime rather than a page-local search script. The input keeps an explicit accessible name even when the compact example omits a visible label.

API Reference

Styled Component API

These props are added or materially changed by the installed Astro styled component. Standard HTML attributes remain available through the inherited interfaces noted below. Follow the Primitive and Runtime links for lower-level behavior props.

Combobox

Inherits div attributes. Omits `defaultValue` and `onChange`.

Contains the following additional props:

Prop Type Default

defaultOpen boolean false

Description: Sets the initial open state when the component is uncontrolled.
Classification: Primitive override
Primitive prop: combobox.Root.defaultOpen

disabled boolean false

Description: Disables interaction with the component.
Classification: Primitive override
Primitive prop: combobox.Root.disabled

required boolean false

Description: Marks the control as required for form validation.
Classification: Primitive override
Primitive prop: combobox.Root.required

Combobox Input Group

Inherits div attributes.

Contains the following additional props:

Prop Type Default

size "sm" | "md" | "lg" "md"

Description: Selects the component's visual size.
Classification: Styled variant

Combobox Input

Inherits input attributes.

Contains the following additional props:

Prop Type Default

showClear boolean false

Description: Shows the generated clear-value control.
Classification: Wrapper prop

showTrigger boolean true

Description: Shows the generated popup trigger.
Classification: Wrapper prop

Combobox Trigger

Inherits button attributes.

Contains the following additional props:

Prop Type Default

asChild boolean false

Description: Merges the component behavior and props into its child element.
Classification: Primitive override
Primitive prop: combobox.Trigger.asChild

iconClass string —

Description: Adds classes to the component's generated icon.
Classification: Wrapper prop

showIcon boolean true

Description: Shows the component's generated icon.
Classification: Wrapper prop

Combobox Clear

Inherits button attributes.

Contains the following additional props:

Prop Type Default

asChild boolean false

Description: Merges the component behavior and props into its child element.
Classification: Primitive override
Primitive prop: combobox.Clear.asChild

showIcon boolean true

Description: Shows the component's generated icon.
Classification: Wrapper prop

Combobox Value

Inherits span attributes.

Contains the following additional props:

Prop Type Default

placeholder string —

Description: Provides fallback text when no value is available.
Classification: Wrapper prop

Combobox Content

Inherits div attributes.

Contains the following additional props:

Prop Type Default

size "sm" | "md" | "lg" "md"

Description: Selects the component's visual size.
Classification: Wrapper prop

Combobox Item

Inherits div attributes. Omits `role`.

Contains the following additional props:

Prop Type Default

disabled boolean false

Description: Disables interaction with the component.
Classification: Styled variant
Primitive prop: combobox.Item.disabled

indicatorClass string —

Description: Adds classes to the generated selection indicator.
Classification: Wrapper prop

inset boolean false

Description: Adds leading inset spacing for visual alignment.
Classification: Styled variant

showIndicator boolean true

Description: Shows the generated selection indicator.
Classification: Wrapper prop

value Required string —

Description: Controls or identifies the component value.
Classification: Primitive override
Primitive prop: combobox.Item.value

Primitive And Runtime API

Use these references when you need the lower-level behavior APIs behind Combobox.

Primitive API

Combobox Primitive

Runtime API

Combobox primitive: createCombobox from @starwind-ui/runtime/combobox

Changelog

v1.0.0

Added the dedicated Runtime-backed Combobox with filtering and clearing, replacing the legacy Select search pattern.
See the Combobox Primitive for the underlying unstyled anatomy and behavior API.