Forms & Input
Combobox
Searchable select built from `Popover` + `Command` — API shaped like the shadcn combobox docs, without `@base-ui/react`. Use composable primitives or the `ComboboxSelect` preset for `{ label, value }[]`. Make the expected input clear before someone interacts, and keep the current value, help text and validation feedback connected. Import it from @/components/kamod-ui/combobox.
Source · Design reference · API reference · Theming · Styles
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthInstallation
Import combobox primitives (and optionally ComboboxSelect) from @/components/kamod-ui/combobox.
pnpm add @kamod-ch/uiCopy an example with @kamod-ch/ui or the matching @kamod-ch/ui/… subpath. The code block switches between those two installs. Connect The Global Theme CSS and Tailwind Source Detection before your first render.
Usage
Combobox supports single or multiple selection (value / onValueChange as string or string[]). liftedFilter shares the filter string between ComboboxInlineInput or ComboboxChipsInput and the list (Command stays mounted via forceMount on content). Set autoHighlight on the root (or ComboboxCommand) for first-match highlight plus ArrowUp/Down and Enter — works in ComboboxInput, ComboboxInlineInput, and ComboboxChipsInput via commandNavRef. showClear + ComboboxClear clears selection and filter. Multi-select: ComboboxChips + ComboboxChip + ComboboxChipsInput (implies liftedFilter). ComboboxSelect maps props to these patterns (liftedFilter, multiple, showClear, autoHighlight).
import { Combobox } from "@kamod-ch/ui";Choose a complete composition from the examples below; required child components and props vary by pattern.
Component Examples & Variants
Explore Combobox in Different Contexts, from the starting pattern to the compositions below. Begin with Basic, then compare the examples that match your content, state and layout. These are working patterns to adapt, not a list of interchangeable variant values: check the API Reference before using a prop or combining behaviors. Look at the surrounding labels, supporting text and spacing as well as the component itself.
Read the Result and Its Implementation Together. Use each showcase’s Code view to inspect imports and composition, or its Prompt view to prepare a setup or adaptation brief. Try the narrow preview and local theme controls before connecting real data, and use Reset to return an example to its initial state. Keep layout changes in class utilities where appropriate; follow the Component Styles Guide for hierarchy and the Theming Guide for shared surfaces and colors. The Accessibility Notes explain what to preserve when making those changes.
Basic
Use Search When the Choice List Needs It. Start with a string-based option list and an initial selection to understand the combobox's search-and-select flow. The trigger displays the chosen value, while the chevron indicates that more choices are available in the popup.
Keep the selected value recognizable after closing the panel and provide an empty-result message; a plain Select may be simpler for a very small list.
// combobox-doc.tsx — ComboboxBasicPreviewPreset: ComboboxSelect
Keep Stored Values Separate from Display Labels. Use ComboboxSelect with options shaped as { label, value } when the standard selection layout fits your interface. It packages the common composition while keeping display labels separate from the values stored by the application.
Use those identifiers in application state, and check how the control behaves when an option disappears or its translated label changes after selection.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthControlled
Coordinate the Selection with the Rest of the Form. Pass value and handle onValueChange to keep the combobox selection in parent state. An active-row checkmark can reinforce that selection in the popup while the trigger shows the same current value.
Decide how clearing and unavailable values should be handled, especially when the option list is refreshed asynchronously.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthCustom Row Content
Help Users Distinguish Similar Choices. Place ItemTitle and ItemDescription inside each ComboboxItem for options that need more context than a short label. The richer presentation helps distinguish similar choices without changing the value assigned to each option.
Keep each option's main label concise and avoid nesting unrelated interactive controls inside an option row.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthGroups + Separator
Organize a Long List Around Recognizable Categories. Use ComboboxGroup to organize related choices and ComboboxSeparator to distinguish groups such as timezone regions. Grouping makes the option set easier to scan before or alongside filtering.
Keep search useful across groups and preserve clear separators; too many tiny categories can make a filtered list harder to scan than a flat set of choices.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthInvalid
Explain the Missing or Unacceptable Selection. Apply aria-invalid to the combobox trigger when the selected value fails validation, and coordinate it with the surrounding field. A visible error should explain what choice is needed while the current value remains inspectable.
Associate a specific message with the control, keep its label visible, and decide whether the error should clear immediately on selection or after the next validation step.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthDisabled
Make Unavailable Selection Understandable. Set disabled on Combobox to make its trigger unavailable as a whole. Keep the selected label visible so the form still communicates its current data even when that choice cannot presently be changed.
Explain prerequisites outside the disabled trigger, since users cannot rely on opening it for help. When a related field makes the choice available again, check whether the previous selection is still valid before retaining it.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthAuto-Highlight + Keyboard
Distinguish the Highlighted Option from the Selected Value. Enable autoHighlight to highlight the first visible result after filtering. Arrow keys can move the highlighted row and Enter can activate it; highlighting is a navigation aid rather than a stored selection by itself.
Test filtering, arrow navigation and Enter together, and make sure an empty result never appears to have a valid highlighted choice.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthInline Input Trigger (Base UI Style)
Make the Editable Query Feel Like the Primary Control. Combine liftedFilter and autoHighlight when the visible field should act directly as the search input. Results open below it, reducing the steps between typing a query and selecting a matching option.
Explain whether the field accepts only listed values or arbitrary text, and keep query state distinct from the committed selection when the panel opens and closes.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthMulti-Select + Chips
Keep a Growing Selection Manageable. Set multiple on ComboboxSelect to represent selected values as chips alongside ComboboxChipsInput. The onValueChange callback receives a string[], so the application can store the collection as one explicit field value.
Give removal actions useful names, handle duplicate values consistently, and test long labels and many selections so the field remains usable without horizontal overflow.
Interactive preview
Preact example Local preview theme · Responsive styles follow the preview widthFull widthProps and Data
Configure Combobox using the contracts below. Read the documented options alongside the Source Definitions to understand which values your application supplies and which details the component owns. Start with a prop or helper, then follow its type link to inspect the declaration without leaving the page.
Props, slots and variants for this component.
Type cards are extracted from this checkout’s TypeScript source at build time. Props inherited through HTMLAttributes, Omit or variant helpers remain references in those declarations; their fields are not flattened here. Match the reference to your installed version, and check a package’s exports before writing an import type. A type exported by a source file is not necessarily re-exported by @kamod-ch/ui.
Component Props
? means a field can be omitted; it does not promise a fallback value. Existing documented defaults remain alongside the descriptions. For callbacks, check the argument and return types before connecting your own state or services.Combobox
ComboboxProps
| Prop / type | Description |
|---|---|
autoHighlight | Highlight first match and enable ArrowUp/Down + Enter in filter inputs (requires `ComboboxCommand autoHighlight` or preset).
|
children | Configure
|
class | Configure
|
closeOnSelect | When `multiple`, defaults to `false`; when single, defaults to `true`.
|
defaultOpen | Configure
|
defaultValue | Configure
|
disabled | Configure
|
itemKey | Configure
|
items | Configure
|
itemToStringValue | Configure
|
liftedFilter | Share filter text between trigger input and `Command` (Base UI–style single input + list in popover).
|
multiple | Configure
|
onOpenChange | Configure
|
onValueChange | Emits `string` when `multiple` is false, else `string[]`.
|
open | Configure
|
placeholder | Configure
|
showClear | Configure
|
value | Configure
|
ComboboxChip
ComboboxChipProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
itemKey | Configure
|
ComboboxChips
ComboboxChipsProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
onClick | Configure
|
ComboboxChipsInput
ComboboxChipsInputProps
| Prop / type | Description |
|---|---|
class | Configure
|
onFocus | Configure
|
onInput | Configure
|
onKeyDown | Configure
|
ComboboxClear
ComboboxClearProps
| Prop / type | Description |
|---|---|
class | Configure
|
onClick | Configure
|
ComboboxCommand
CommandProps
| Prop / type | Description |
|---|---|
autoHighlight | First visible item gets `data-highlighted`; enables ArrowUp/Down + Enter in `CommandInput`.
|
children | Configure
|
class | Configure
|
hasVisibleItems | External visibility signal; updated by `CommandList` when provided.
|
query | External filter signal (e.g. combobox inline input shares query with the list).
|
ComboboxContent
PopoverContentProps
| Prop / type | Description |
|---|---|
align | Configure
|
children | Configure
|
class | Configure
|
forceMount | Configure
|
side | Configure
|
sideOffset | Configure
|
ComboboxEmpty
CommandEmptyProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
ComboboxGroup
CommandGroupProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
heading | Configure
|
ComboboxInlineInput
ComboboxInlineInputProps
| Prop / type | Description |
|---|---|
class | Configure
|
onFocus | Configure
|
onInput | Configure
|
onKeyDown | Configure
|
ComboboxInput
CommandInputProps
| Prop / type | Description |
|---|---|
class | Configure
|
ComboboxItem
ComboboxItemProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
disabled | Configure
|
item | Configure
|
onClick | Configure
|
ComboboxList
ComboboxListProps
| Prop / type | Description |
|---|---|
children | Configure
|
items | Configure
|
onMount | Notified when the list root mounts (e.g. combobox inline input forwards keyboard to the list).
|
ComboboxSelect
ComboboxSelectProps
| Prop / type | Description |
|---|---|
autoHighlight | Highlight first match and enable ArrowUp/Down + Enter in filter inputs (requires `ComboboxCommand autoHighlight` or preset).
|
class | Configure
|
closeOnSelect | When `multiple`, defaults to `false`; when single, defaults to `true`.
|
defaultOpen | Configure
|
defaultValue | Configure
|
disabled | Configure
|
emptyText | Configure
|
liftedFilter | Share filter text between trigger input and `Command` (Base UI–style single input + list in popover).
|
multiple | Configure
|
onOpenChange | Configure
|
onValueChange | Emits `string` when `multiple` is false, else `string[]`.
|
open | Configure
|
options | Configure
|
placeholder | Configure
|
searchPlaceholder | Configure
|
showClear | Configure
|
triggerClass | Configure
|
value | Configure
|
ComboboxSeparator
CommandSeparatorProps
| Prop / type | Description |
|---|---|
class | Configure
|
ComboboxTrigger
PopoverTriggerProps
| Prop / type | Description |
|---|---|
asChild | Configure
|
children | Configure
|
class | Configure
|
disabled | Configure
|
ComboboxValue
ComboboxValueProps
| Prop / type | Description |
|---|---|
children | Configure
|
class | Configure
|
placeholder | Configure
|
Data Type Reference
Expand a card to inspect and copy the exact declaration. The code header identifies its repository file; follow imported or inherited types in the Implementation Source when you need the complete dependency chain. Required-field summaries cover fields declared directly in that type. Source-only helpers and inferred schema outputs describe the local implementation, not additional props you can pass to every component.
ComboboxChip Props
2 declared fieldsComboboxChipPropsComboboxChip.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of ComboboxChipProps before adapting it.itemKeyComboboxChips Props
1 declared fieldComboboxChipsPropsComboboxChips.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of ComboboxChipsProps before adapting it.ComboboxChipsInput Props
DeclarationComboboxChipsInputPropsComboboxChipsInput.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of ComboboxChipsInputProps before adapting it.ComboboxClear Props
DeclarationComboboxClearPropsComboboxClear.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of ComboboxClearProps before adapting it.ComboboxInlineInput Props
DeclarationComboboxInlineInputPropsComboboxInlineInput.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of ComboboxInlineInputProps before adapting it.ComboboxItem Props
1 declared fieldComboboxItemPropsComboboxItem.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of ComboboxItemProps before adapting it.itemComboboxList Props
2 declared fieldsComboboxListPropsComboboxList.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of ComboboxListProps before adapting it.childrenComboboxOption
2 declared fieldsComboboxOptionComboboxSelect.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of ComboboxOption before adapting it.label, valueComboboxSelect Props
4 declared fieldsComboboxSelectPropsComboboxSelect.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of ComboboxSelectProps before adapting it.optionsComboboxValue Props
2 declared fieldsComboboxValuePropsComboboxValue.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of ComboboxValueProps before adapting it.ComboboxCommandNav
2 declared fieldsComboboxCommandNavcombobox-context.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of ComboboxCommandNav before adapting it.moveHighlight, activateHighlightedComboboxContextValue
22 declared fieldsComboboxContextValuecombobox-context.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of ComboboxContextValue before adapting it.items, leafItems, itemToString, itemKey, selectedKeys, selectedKey, multiple, isSelected, selectByItem, toggleByItem, removeKey, clearSelection, placeholder, disabled, liftedFilter, filterQuery, hasVisibleItems, autoHighlight, showClear, closeOnSelect, comboboxListRef, commandNavRefCombobox Props
17 declared fieldsComboboxPropscombobox-context.tsx. Referenced types retain their original names; inspect that file for imports and supporting definitions. Inspect the Complete Definition of ComboboxProps before adapting it.Accessibility
Build the Complete Interaction, Including the Parts Outside Combobox. The notes below distinguish the current implementation from the labels, content and behavior your application supplies. Start with the Live Preview, check the Props and Data Reference, and test the finished composition with real content rather than assuming that an unchanged visual example covers every use case.
Built-in Behavior and Defaults
Combobox composes selection, search and popover/command pieces. Arrow highlighting is controlled by autoHighlight, which defaults to false in the convenience composition. Do not infer a complete ARIA combobox contract solely from the component name.
Labels and Relationships
Label the trigger and any separate search input according to their jobs. A filter placeholder is a hint, not a persistent label. Selected chips need identifiable removal actions; the default short Remove name may need extra context in a multi-selection interface.
Keyboard and Focus
With autoHighlight enabled, supported input handlers use Up/Down to move the highlight and Enter to activate it. Check the exact composition you use, including empty results, clearing, closing and focus return; visual highlighting alone does not guarantee that active results are announced.
States and Integration Details
Keep loading, no matches and no selection as separate states. Verify the rendered input/list relationship and screen-reader output before adopting the control for a critical workflow. Do not add combobox roles without the associated focus and state behavior.
Verify the Complete Interaction
Check Behavior as Well as Markup. Work through these scenarios in the application where the component will be used. Automated checks can help find structural problems; also review the reading experience with a screen reader, keyboard focus and the actual feedback from your application.
- Search with the keyboard, select a result, reopen and clear the selection without losing the field label.
- Remove a chip and verify focus goes to a surviving control with a meaningful name.
- Test no matches, asynchronous results and disabled choices with your target screen reader.
Recheck the result after changing Theme Tokens, translations or class overrides. Include text enlargement, narrow layouts and reduced-motion settings where animation is present. Inspect the Component Source when a behavior differs from your expectation; a role or state attribute does not implement keyboard interaction by itself.
For background, read the WAI-ARIA Authoring Guidance and Keyboard Interface Guidance. These explain the patterns; verify browser and assistive-technology behavior for the implementation and audience you actually support.
You have the pieces. Put them into one real interaction, keep its state in one place, and check the result with the content your application will actually show.
Connect the Foundation
Return to Choose and Compose Components to connect this reference to a working screen. Keep global CSS in one entrypoint and import only the components that screen needs.
Build the Surrounding Screen
Find a neighboring interaction in the Component Library, or start with a complete Block. Replace sample content and destinations before refining the layout; a local class change can stay with the composition.
Make the Result Hold Up
Use shared theme roles for changes that belong everywhere. Then review the whole journey: keyboard focus, long labels, narrow screens and a clear way to recover when something fails.
Keep a link to the source and note your intentional changes. Your next edit should begin with a clear decision, not another search.