Skip to main content

Starwind UI v3.0 is now available! Migration guide

Framework

Installation

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>

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.

Filtering and clearing

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

Closing and Change Reasons

The change callbacks and events include a reason in their details. Cancel a change with details.cancel(). Astro, React, Vue, and Svelte send the same events in the same order.

  • Pressing an item sends the value change, then the input text change with reason item-press, then the open change that closes the list.
  • Pressing the clear button sends the value change, then the input text change to "" with reason clear.
  • Tab and Shift+Tab close the list when focus moves past the input, the trigger, and the clear button, with the open reason focus-out. The list stays open while focus moves among those controls.

Every ComboboxTrigger opens and closes the list, including one that you add beside the input.

Cancel a focus-out close to keep the list open. Focus goes back to the input, and text that you did not commit returns to the previous text, as it does after Escape.

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

Runtime API

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

Changelog

View version history v1.3.0 9 releases

v1.3.0

  • Combobox now closes when focus leaves it. Before, the list stayed open after you pressed Tab or Shift+Tab. The list stays open while focus moves between the input, the trigger, and the clear button. The close uses the new focus-out reason. Call cancel() in onOpenChange to keep the list open.
  • Combobox now sends its events in the same order in every framework. Pressing an item sends the value change, then the input text change with the item-press reason, then the open change. Clearing sends the value change, then the input text change to "" with the clear reason. You can cancel the input text change in every framework.
  • When you cancel a typed change, the input text goes back to the previous text. This now also works in Astro.
  • When your code controls value and keeps it without calling cancel(), the input text now shows the label of the value you kept. When your code controls inputValue, typing in the middle of the text keeps the caret in place. A form reset keeps a value that your code controls.
  • Fixed a Combobox with a ComboboxTrigger that you added yourself. Before, only the trigger inside the input rendered by ComboboxInput worked. Now every trigger opens and closes the list and shows the open and disabled state.
  • Focus now goes back to a trigger after a close only when you have not moved on. Before, this could close a Combobox that you had just opened.
  • Styled ComboboxClear with asChild now uses your child as the button. Before, the default icon made a button inside a button in Vue and React, and a hydration mismatch in Nuxt. Add your own icon to the child if you want one.
  • In React, Combobox now opens on the first focus of its input, as it does in Astro, Vue, and Svelte, and it keeps data-value on the root when a parent changes the value while the list is closed.
  • Fixed a Combobox with more than one ComboboxClear. Before, only the first one worked. Pressing another one did not clear the selection or the text, and inside the input group it opened the list. Now every ComboboxClear clears the selection and the text, and each one shows the disabled state.
  • In Svelte, a Combobox that gets its props through a spread, such as {...props}, now shows the new label when your state changes value. Before, the text field kept the old label while the form sent the new value.
  • In Svelte, Combobox.Root now renders option attributes such as data-modal and data-filter-mode, and its first render shows the open state.
  • In React, Combobox now shows the selected label when your own component renders the items. If your items load later, a value has no label until someone opens the list and picks an item.
  • In Astro, the Combobox input group now renders data-slot="combobox-input-group", as in React.
  • In Svelte, a defined value, inputValue, or open that you pass when Combobox mounts now stays under your control, as in React and Vue. To change it, use bind: or update your state in the change callback. A form reset keeps it. If you pass undefined at mount, Combobox keeps its own state.
  • In Svelte, Combobox.Trigger and Combobox.Clear still need a button in child. With another element they do nothing, and they now log a console error in production as well as in development.
  • In Vue, Styled ComboboxTrigger and ComboboxClear with asChild accept a child, and Combobox.Icon has aria-hidden.
  • In React, Select and Combobox inside a Field with a name now send their value when the form submits, and they call onValueChange, onOpenChange, and onInputValueChange. Before, the form often left the value out, and the callbacks did not run.

v1.2.3

  • A required Combobox now stops a plain HTML form from submitting when no option is selected. The browser shows its message and puts focus in the Combobox input. The list stays closed so it does not cover the message. Before, the empty form submitted, and no message showed.
  • A Combobox without required still lets the Enter key submit the form as before.

v1.2.2

  • Fixed form resets overwriting newer input or changing the value after a reset was canceled. React restores input text after Escape, and Vue restores it after a canceled input change.
  • Reduced background work when a React page uses multiple menus, tooltips, or other portals.
  • Fixed nested Svelte overlays inside a dialog appearing behind their parent or failing to receive clicks.
  • Fixed nested overlays appearing behind their parent in Vue and Svelte. Overlays can now render under the document body; if custom CSS or DOM queries require them to stay inside a parent, set a portal container or add data-floating-root to that parent.
  • Reduced the JavaScript loaded by Combobox when it is used without Field.
  • Fixed React 18 retaining removed popup elements when the parent component stays mounted.

v1.2.1

  • Group headings are now linked to their groups with aria-labelledby, so screen readers announce the name of each group.

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

  • The default export in index.ts now has a name, ComboboxParts, so framework tools show a clear name.

v1.0.1

  • ComboboxInputGroup and ComboboxContent now each show their own size in data-size. When you leave out size, it is md. You do not need to change your props.

v1.0.0

  • Added Combobox, with filtering and a clear button. It gets its behavior from Starwind Runtime. Use it in place of the old Select with search.
  • See the Combobox Primitive for the unstyled parts and the behavior API.