Combobox

Setup

import { Combobox } from '@fragments-sdk/ui';

Examples

Loading preview...

Props

Prop	Type	Default	Description
`multiple`	`boolean`	`false`	Allow multiple selections with chips
`value`	`union`	Not set	Controlled selected value (string for single, string[] for multiple)
`defaultValue`	`union`	Not set	Default selected value (uncontrolled)
`onValueChange`	`union`	Not set	Called when selection changes
`onChange`	`union`	Not set	Alias for onValueChange
`children`Required	`node`	Not set	Combobox input and content
`open`	`boolean`	Not set	Controlled open state of the dropdown
`defaultOpen`	`boolean`	`false`	Initial open state for uncontrolled usage
`onOpenChange`	`function`	Not set	Called when dropdown open state changes
`required`	`boolean`	Not set	—
`name`	`string`	Not set	—
`placeholder`	`string`	Not set	Placeholder text for the input
`autoHighlight`	`boolean`	`true`	Auto-highlight first matching item while filtering
`size`	`enumsmmdlg`	`md`	Size variant
`className`	`string`	Not set	Wrapper class name
`label`	`string`	Not set	Visible label text above the combobox
`helperText`	`string`	Not set	Helper text shown below the combobox
`error`	`union`	Not set	Show error styling. When a string is provided, it is displayed as an error message.
`disabled`	`boolean`	`false`	Disable the combobox

Usage Guidelines

When to use

Users need to search/filter through many options
Large option lists where scrolling is impractical
When users might know what they are looking for
Autocomplete or typeahead functionality
Multiple selections from a searchable list

When not to use

Few options (under 5) - use Select or RadioGroup
Free-form text with no predefined options - use Input
Non-searchable single selection - use Select
Actions, not selection - use Menu

Best practices

Include a placeholder that explains what to search for
Use label prop for accessible field labeling
Use helperText for guidance and error for validation messages
Provide an empty state message when no results match
Group related options with Combobox.Group for large lists
Keep option text concise and searchable
Use multiple prop for multi-select with chip display

Accessibility

Full keyboard navigation support (arrow keys, enter, escape)
Type-ahead filtering within options
Proper ARIA combobox roles and attributes
Screen reader announcements for filtered results
Chip removal via keyboard in multi-select mode

Standards References

Selectalternative

Use Select when search/filtering is not needed

Inputsibling

Use Input for free-form text entry

Listboxsibling

Use Listbox for inline option lists

Setup

Examples

Default

Multiple Selection

With Label and Helper Text

Error State

With Groups

With Empty State

Scrollable List

Custom Max Visible Items

Disabled

Explicit Trigger

Props

Usage Guidelines

When to use

When not to use

Best practices

Standards References

Setup

Examples

Default

Multiple Selection

With Label and Helper Text

Error State

With Groups

With Empty State

Scrollable List

Custom Max Visible Items

Disabled

Explicit Trigger

Props

Usage Guidelines

When to use

When not to use

Best practices

Standards References

Related Components