On this page

Combobox

Framework

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

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

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

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

Installation

pnpx starwind@latest add combobox

npx starwind@latest add combobox

yarn dlx starwind@latest add combobox

Usage

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

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

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

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

Composition

Use this structure for a labeled combobox with a flat list of options:

Combobox
├── ComboboxLabel
├── ComboboxInput
└── ComboboxContent
    ├── ComboboxEmpty
    └── ComboboxItem

ComboboxInput includes its trigger and can show a clear button. Use ComboboxInputGroup when you need to compose ComboboxInput, ComboboxValue, ComboboxTrigger, or ComboboxClear yourself. Groups can contain ComboboxGroupLabel and items. Use ComboboxSeparator between groups.

Sizes

ComboboxInput owns the input-side sm, md, or lg size. ComboboxContent sizes the portaled popup independently, so both scopes can match or differ.

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

{(["sm", "md", "lg"] as const).map((size) => (
  <Combobox defaultValue="astro">
    <ComboboxInput size={size} placeholder={`${size} control`} />
    <ComboboxContent size={size}>
      <ComboboxItem value="astro">Astro</ComboboxItem>
      <ComboboxItem value="react">React</ComboboxItem>
      <ComboboxItem value="vue">Vue</ComboboxItem>
    </ComboboxContent>
  </Combobox>
))}

<Combobox defaultValue="astro">
  <ComboboxInput size="sm" placeholder="Compact control" />
  <ComboboxContent size="lg">
    <ComboboxItem value="astro">Astro</ComboboxItem>
    <ComboboxItem value="react">React</ComboboxItem>
    <ComboboxItem value="vue">Vue</ComboboxItem>
  </ComboboxContent>
</Combobox>

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

export function Example() {
  return (
    <>
      {(["sm", "md", "lg"] as const).map((size) => (
        <Combobox key={size} defaultValue="astro">
          <ComboboxInput size={size} placeholder={`${size} control`} />
          <ComboboxContent size={size}>
            <ComboboxItem value="astro">Astro</ComboboxItem>
            <ComboboxItem value="react">React</ComboboxItem>
            <ComboboxItem value="vue">Vue</ComboboxItem>
          </ComboboxContent>
        </Combobox>
      ))}

      <Combobox defaultValue="astro">
        <ComboboxInput size="sm" placeholder="Compact control" />
        <ComboboxContent size="lg">
          <ComboboxItem value="astro">Astro</ComboboxItem>
          <ComboboxItem value="react">React</ComboboxItem>
          <ComboboxItem value="vue">Vue</ComboboxItem>
        </ComboboxContent>
      </Combobox>
    </>
  );
}

Filtering and clearing

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

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

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

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

export function Example() {
  return (
    <>
      <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>
    </>
  );
}

API Reference

Styled Component API

These props are added or materially changed by the installed styled component. Standard HTML attributes remain available through the inherited interfaces noted below. Expand a prop to see named type definitions and framework-specific imports. 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. Omits `size`.

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

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

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

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

disablePortal boolean false

Description: Keeps the public Portal wrapper inline instead of moving it to a target.
Classification: Wrapper prop

portalContainer string —

Description: Sets the CSS selector for the public Portal wrapper target.
Classification: Wrapper prop

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

View version history v1.2.0 5 releases

v1.2.0

Added portalContainer and disablePortal to ComboboxContent for custom portal targets and inline rendering.

v1.1.0

The popup now closes with fade and scale motion without sliding toward the trigger.
ComboboxInput now accepts size="sm", size="md", or size="lg" and keeps the built-in trigger and chevron at every size. ComboboxContent continues to size the popup independently.
ComboboxInputGroup remains available for advanced custom composition.

v1.0.2

Named the generated aggregate default export so React and Astro tooling can identify the installed component cleanly.

v1.0.1

ComboboxInputGroup and ComboboxContent now expose independent data-size scopes and resolve omitted sizes to md. No prop migration is required.

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.

Layer Metadata

Combobox uses the Combobox primitive for its behavior foundation. Combobox is available for Astro and React.

styled-component Combobox Combobox uses the Combobox primitive for its behavior foundation. Combobox is available for Astro and React. Styled component Behavior Foundation combobox direct-primitive Direct primitive /docs/components/combobox/ ComboboxClear ComboboxContent ComboboxEmpty ComboboxGroup ComboboxGroupLabel ComboboxInput ComboboxInputGroup ComboboxItem ComboboxItemIndicator ComboboxItemText ComboboxLabel ComboboxSeparator ComboboxTrigger ComboboxValue Root Label InputGroup Input Trigger Clear Value Content Empty Group GroupLabel Item ItemText ItemIndicator Separator ComboboxVariants Form & Input forms inputs controls astro react comboboxClear comboboxContent comboboxEmpty comboboxGroup comboboxGroupLabel comboboxInput comboboxInputGroup comboboxItem comboboxItemIndicator comboboxItemText comboboxLabel comboboxList comboboxSeparator comboboxTrigger comboboxValue combobox-clear combobox-content combobox-empty combobox-group combobox-group-label combobox-input combobox-input-group combobox-item combobox-item-indicator combobox-item-text combobox-label combobox-list combobox-portal combobox-positioner combobox-separator combobox-trigger combobox-value /docs/primitives/combobox/ Primitive Combobox createCombobox @starwind-ui/runtime/combobox /docs/runtime/#create-combobox Runtime factory createCombobox Astro available Available Astro available React React available defaultOpen boolean Primitive override false Sets the initial open state when the component is uncontrolled. disabled Disables interaction with the component. required Marks the control as required for form validation. div attributes size "sm" | "md" | "lg" Styled variant "md" Selects the component's visual size. sm md lg showClear Wrapper prop Shows the generated clear-value control. showTrigger true Shows the generated popup trigger. input attributes asChild Merges the component behavior and props into its child element. iconClass string Adds classes to the component's generated icon. showIcon Shows the component's generated icon. button attributes placeholder Provides fallback text when no value is available. span attributes disablePortal Keeps the public Portal wrapper inline instead of moving it to a target. portalContainer Sets the CSS selector for the public Portal wrapper target. indicatorClass Adds classes to the generated selection indicator. inset Adds leading inset spacing for visual alignment. showIndicator Shows the generated selection indicator. value Controls or identifies the component value.