Combobox
---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> );}<script setup lang="ts">import { Combobox, ComboboxContent, ComboboxEmpty, ComboboxInput, ComboboxItem, ComboboxLabel,} from "@/components/starwind/combobox";</script>
<template> <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></template><script lang="ts"> import { Combobox, ComboboxContent, ComboboxEmpty, ComboboxInput, ComboboxItem, ComboboxLabel, } from "@/components/starwind/combobox";</script>
<div class="w-full max-w-sm"> <Combobox id="combobox-framework" 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></div>Installation
pnpx starwind@latest add combobox --framework astronpx starwind@latest add combobox --framework astroyarn dlx starwind@latest add combobox --framework astropnpx starwind@latest add combobox --framework reactnpx starwind@latest add combobox --framework reactyarn dlx starwind@latest add combobox --framework reactpnpx starwind@latest add combobox --framework vuenpx starwind@latest add combobox --framework vueyarn dlx starwind@latest add combobox --framework vuepnpx starwind@latest add combobox --framework sveltenpx starwind@latest add combobox --framework svelteyarn dlx starwind@latest add combobox --framework svelteUsage
---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> );}<script setup lang="ts">import { Combobox, ComboboxContent, ComboboxEmpty, ComboboxInput, ComboboxItem, ComboboxLabel,} from "@/components/starwind/combobox";</script>
<template> <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></template><script lang="ts"> import { Combobox, ComboboxContent, ComboboxEmpty, ComboboxInput, ComboboxItem, ComboboxLabel, } from "@/components/starwind/combobox";</script>
<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 └── ComboboxItemComboboxInput 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> </> );}<script setup lang="ts">import { Combobox, ComboboxContent, ComboboxInput, ComboboxItem,} from "@/components/starwind/combobox";</script>
<template> <template v-for="size in ['sm', 'md', 'lg'] as const" :key="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></template >
<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></template><script lang="ts"> import { Combobox, ComboboxContent, ComboboxInput, ComboboxItem, } from "@/components/starwind/combobox";</script>
{#each ["sm", "md", "lg"] as const as size (size)} <Combobox defaultValue="astro"> <ComboboxInput {size} placeholder={`${size} control`} /> <ComboboxContent {size}> <ComboboxItem value="astro">Astro</ComboboxItem> <ComboboxItem value="react">React</ComboboxItem> <ComboboxItem value="vue">Vue</ComboboxItem> </ComboboxContent> </Combobox>{/each}<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> </> );}<script setup lang="ts">import { Combobox, ComboboxContent, ComboboxEmpty, ComboboxInput, ComboboxItem,} from "@/components/starwind/combobox";</script>
<template> <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></template><script lang="ts"> import { Combobox, ComboboxContent, ComboboxEmpty, ComboboxInput, ComboboxItem, } from "@/components/starwind/combobox";</script>
<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>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 reasonclear. - 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:
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:
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:
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:
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:
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:
placeholder string —
- Description
- Provides fallback text when no value is available.
- Classification
- Wrapper prop
Combobox Content
Inherits div attributes.
Contains the following additional props:
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:
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
createComboboxfrom@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-outreason. Callcancel()inonOpenChangeto 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-pressreason, then the open change. Clearing sends the value change, then the input text change to""with theclearreason. 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
valueand keeps it without callingcancel(), the input text now shows the label of the value you kept. When your code controlsinputValue, 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
ComboboxTriggerthat you added yourself. Before, only the trigger inside the input rendered byComboboxInputworked. 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
ComboboxClearwithasChildnow 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-valueon 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 everyComboboxClearclears 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 changesvalue. Before, the text field kept the old label while the form sent the new value. - In Svelte,
Combobox.Rootnow renders option attributes such asdata-modalanddata-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, oropenthat you pass when Combobox mounts now stays under your control, as in React and Vue. To change it, usebind:or update your state in the change callback. A form reset keeps it. If you passundefinedat mount, Combobox keeps its own state. - In Svelte,
Combobox.TriggerandCombobox.Clearstill need a button inchild. With another element they do nothing, and they now log a console error in production as well as in development. - In Vue, Styled
ComboboxTriggerandComboboxClearwithasChildaccept a child, andCombobox.Iconhasaria-hidden. - In React, Select and Combobox inside a
Fieldwith anamenow send their value when the form submits, and they callonValueChange,onOpenChange, andonInputValueChange. Before, the form often left the value out, and the callbacks did not run.
v1.2.3
- A
requiredCombobox 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
requiredstill 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-rootto 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
portalContaineranddisablePortaltoComboboxContentfor custom portal targets and inline rendering.
v1.1.0
- The popup now closes with fade and scale motion without sliding toward the trigger.
ComboboxInputnow acceptssize="sm",size="md", orsize="lg"and keeps the built-in trigger and chevron at every size.ComboboxContentcontinues to size the popup independently.ComboboxInputGroupremains available for advanced custom composition.
v1.0.2
- The default export in
index.tsnow has a name,ComboboxParts, so framework tools show a clear name.
v1.0.1
ComboboxInputGroupandComboboxContentnow each show their own size indata-size. When you leave outsize, it ismd. 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.