ComboboxSelect
An options-driven combobox for searchable, grouped, remote, multiple, and creatable selection.
Controls
import { ComboboxSelect } from "raft-ui/wip";
<ComboboxSelect
options={options}
value={value}
onValueChange={setValue}
clearable
aria-label="Choose an option"
/>Pass a flat options array or a grouped array. Each option uses value, label, and an optional disabled flag.
Grouped models + filter
Multiple + maxTagCount
Shanghai
London
Remote search
Creatable
Use grouped options when related models belong to the same provider. The component keeps filtering, keyboard navigation, disabled options, and selection state together.
Search by model or provider.
Set remote to keep filtering in the caller and use onSearch to request the next result window.
Load options when the popup opens and use fallbackOption to keep an already selected value readable while results are loading.
Keep the popup open while a selection is being saved and expose the pending state through loading.
optionsreadonly (Option | ComboboxSelectGroup<Option>)[]
Options to display. A group contains a key, label, and children array for grouped results.
valueComboboxSelectSelection<Multiple>
Controls the selected option or options.
defaultValueComboboxSelectSelection<Multiple>
Sets the initial selected option or options for an uncontrolled component.
onValueChange(value, options, details) => void
Called after a selectable option is chosen, removed, or cleared.
multipledefault: falseboolean
Enables multiple values and removable chips in the control.
labelFielddefault: "label"keyof Option
Names the option field used for the visible label.
valueFielddefault: "value"keyof Option
Names the option field used as the selected value.
disabledFielddefault: "disabled"keyof Option
Names the option field that marks an option as unavailable.
filterabledefault: trueboolean
Enables local filtering as the user types.
filterfalse | ((query, option) => boolean)
Replaces the default local matching function for each option.
remotedefault: falseboolean
Keeps filtering under the caller's control for remote result sets.
onSearch(query) => void
Receives the current query so the caller can request remote options.
loadingdefault: falseboolean
Shows loading content and prevents option selection while results are pending.
createdefault: falseboolean
Adds a creation row when the query does not match an existing option.
creatableboolean
Alias for create when using a creatable naming convention.
onCreate(query) => Option | null
Builds the new option, or returns null to reject the creation.
fallbackOption(value) => Option
Provides a label for a selected value that is outside the current result window.
clearabledefault: falseboolean
Shows a clear action when the control has a selected value.
showArrowdefault: trueboolean
Shows the trigger arrow used to open and close the options popup.
clearFilterAfterSelectdefault: trueboolean
Clears the search query after an option is selected.
onClear() => void
Runs after the current selection is cleared.
maxTagCountnumber
Limits visible chips when multiple values are selected and shows an overflow count.
sizedefault: "md""sm" | "md" | "lg"
Sets the control's density and text scale.
status"error" | "warning"
Applies a validation border state to the control.
placeholderdefault: "Select an option"string
Text shown while no option is selected.
classNamestring
Adds classes to the control and can be used to set its width.
styleCSSProperties
Adds inline styles to the control. The popup follows the control width.
renderLabel(option) => ReactNode
Customizes the selected label while keeping the option value unchanged.
renderOption(option, info) => ReactNode
Customizes option content while preserving selection and keyboard behavior.
renderTag(option) => ReactNode
Customizes the chip content used for multiple selected values.
renderCreateLabeldefault: Create “{query}”(query) => ReactNode
Customizes the text shown in the creation row.
emptyContentdefault: "No options found"ReactNode
Content shown when no options match the current query.
loadingContentdefault: "Loading…"ReactNode
Content shown while remote options or an async selection is loading.
messagesPartial<ComboboxSelectMessages>
Overrides accessible labels for clearing, toggling, selection, and chip removal.
| Prop | Type | Default | Description |
|---|---|---|---|
options | readonly (Option | ComboboxSelectGroup<Option>)[] | — | Options to display. A group contains a key, label, and children array for grouped results. |
value | ComboboxSelectSelection<Multiple> | — | Controls the selected option or options. |
defaultValue | ComboboxSelectSelection<Multiple> | — | Sets the initial selected option or options for an uncontrolled component. |
onValueChange | (value, options, details) => void | — | Called after a selectable option is chosen, removed, or cleared. |
multiple | boolean | false | Enables multiple values and removable chips in the control. |
labelField | keyof Option | "label" | Names the option field used for the visible label. |
valueField | keyof Option | "value" | Names the option field used as the selected value. |
disabledField | keyof Option | "disabled" | Names the option field that marks an option as unavailable. |
filterable | boolean | true | Enables local filtering as the user types. |
filter | false | ((query, option) => boolean) | — | Replaces the default local matching function for each option. |
remote | boolean | false | Keeps filtering under the caller's control for remote result sets. |
onSearch | (query) => void | — | Receives the current query so the caller can request remote options. |
loading | boolean | false | Shows loading content and prevents option selection while results are pending. |
create | boolean | false | Adds a creation row when the query does not match an existing option. |
creatable | boolean | — | Alias for create when using a creatable naming convention. |
onCreate | (query) => Option | null | — | Builds the new option, or returns null to reject the creation. |
fallbackOption | (value) => Option | — | Provides a label for a selected value that is outside the current result window. |
clearable | boolean | false | Shows a clear action when the control has a selected value. |
showArrow | boolean | true | Shows the trigger arrow used to open and close the options popup. |
clearFilterAfterSelect | boolean | true | Clears the search query after an option is selected. |
onClear | () => void | — | Runs after the current selection is cleared. |
maxTagCount | number | — | Limits visible chips when multiple values are selected and shows an overflow count. |
size | "sm" | "md" | "lg" | "md" | Sets the control's density and text scale. |
status | "error" | "warning" | — | Applies a validation border state to the control. |
placeholder | string | "Select an option" | Text shown while no option is selected. |
className | string | — | Adds classes to the control and can be used to set its width. |
style | CSSProperties | — | Adds inline styles to the control. The popup follows the control width. |
renderLabel | (option) => ReactNode | — | Customizes the selected label while keeping the option value unchanged. |
renderOption | (option, info) => ReactNode | — | Customizes option content while preserving selection and keyboard behavior. |
renderTag | (option) => ReactNode | — | Customizes the chip content used for multiple selected values. |
renderCreateLabel | (query) => ReactNode | Create “{query}” | Customizes the text shown in the creation row. |
emptyContent | ReactNode | "No options found" | Content shown when no options match the current query. |
loadingContent | ReactNode | "Loading…" | Content shown while remote options or an async selection is loading. |
messages | Partial<ComboboxSelectMessages> | — | Overrides accessible labels for clearing, toggling, selection, and chip removal. |