| ariaLabel | - | string |
Provides an accessible name for the options of the panel. |
| ariaSearchLabel | Search options | string |
Provides an accessible name for the search field. |
| caretIcon | (
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" fill="currentColor">
<path d="M256 382.627 60.687 187.313l22.626-22.626L256 337.372l172.687-172.685 22.626 22.626z" />
</svg>
) | ReactNode |
The caret drawn at the end of the toggle. Pass false to draw none. |
| children | - | ReactNode |
The options, as CListBoxOption and CListBoxSection elements. Pass items instead to render them from data. |
| className | - | string |
Adds custom classes to the React Combobox toggle. |
| container | - | Element, DocumentFragment, (() => Element | DocumentFragment | null), null |
The element the panel is rendered into instead of document.body. Implies portal. Inside a modal dialog it goes into the dialog instead, because the rest of the page is inert. |
| defaultShow | - | boolean |
The initial open state of the uncontrolled panel — read once on mount. |
| defaultValue | - | string, string[], null |
The initial value for the uncontrolled mode. Ignored when value is set. |
| disabled | - | boolean |
Turns the toggle off, so the panel cannot be opened. |
| feedback4.2.0+ | - | ReactNode |
Feedback for the current validationState — rendered only while the state is set, and styled after it. For the client-side mode, where the browser owns the state, use feedbackValid and feedbackInvalid instead. |
| feedbackInvalid4.2.0+ | - | ReactNode |
Feedback the stylesheet reveals while the control is invalid — always rendered, so it works with client-side validation, where the browser decides the state. |
| feedbackValid4.2.0+ | - | ReactNode |
Feedback the stylesheet reveals while the control is valid — always rendered, so it works with client-side validation, where the browser decides the state. |
| floatingLabel4.2.0+ | - | ReactNode |
Provide a floating label for the component — the text rests inside the field and floats once it has focus or a value. |
| floatingLabelAlways6.0.0+ | - | boolean |
Keeps the floating label floated and the placeholder visible while the field is empty. |
| indicator | none | ListBoxIndicator |
Puts a mark in front of every option. checkbox renders the check the multi-value pickers use. |
| items | - | ListBoxOption[] |
Renders the options from data instead of children. |
| label4.2.0+ | - | ReactNode |
Add a caption for a component. |
| multiple | - | boolean |
Toggles options instead of replacing the selection, and keeps the panel open while the user picks. |
| name | - | string |
Name of the hidden select the value is submitted under. With multiple it posts one key per value, as a <select multiple> does: tags=a&tags=b&tags=c. Without a name the combobox is not submitted with the form. |
| onChange | - | ((value: string | string[] | null) => void) |
Callback fired when the value changes. It reports an array in multiple mode, empty when nothing is selected; otherwise a string, or null once the single selection is cleared. |
| onHide | - | (() => void) |
Callback fired when the panel closes. |
| onSearch | - | ((query: string) => void) |
Callback fired with the query of the search field, every time it changes. |
| onSelectionLimit | - | ((limit: number, value: string) => void) |
Callback fired when selectionLimit refuses a pick. It reports the limit and the value that did not fit. |
| onShow | - | (() => void) |
Callback fired when the panel opens. |
| onShowChange | - | ((show: boolean) => void) |
Callback fired when a gesture asks the panel to open or to close. In controlled mode update show yourself, or the panel stays as it is. |
| onValidationStateChange6.0.0+ | - | ((validationState: ValidationState | undefined) => void) |
Callback fired with undefined when the user picks a different value, or the form is reset, while validationState is set. A given state is a verdict on the value it was given for; clear it here to let the browser's own validation show again. |
| placeholder | - | ReactNode |
The text the toggle shows while nothing is selected. |
| portal | - | boolean |
Renders the panel through a portal: into the open <dialog> the field sits in, otherwise into document.body. |
| required6.0.0+ | - | boolean |
Makes the hidden select that carries the value required, so an empty combobox blocks the submit. |
| search | - | boolean, 'external' |
Puts a search field at the top of the panel and hides what does not match. 'external' hides nothing and only reports the query through onSearch. |
| searchNormalize | - | boolean |
Compares the query and the option labels without their diacritics, so zoe finds Zoë. |
| searchPlaceholder | Search | string |
The placeholder of the search field. |
| selectedLabel | '{count} selected' | CountLabel |
The text the toggle shows past one selected value in multiple mode. A function (count, total) => string, or a string in which {count} and {total} are replaced. |
| selectionLimit | - | number |
The number of values multiple mode accepts. |
| show | - | boolean |
The controlled open state of the panel. Pair it with onShowChange. |
| size | - | 'sm', 'lg' |
Size the toggle small or large. |
| text4.2.0+ | - | ReactNode |
Add helper text to the component. |
| tooltipFeedback4.2.0+ | - | boolean |
Display validation feedback in a styled tooltip. |
| typeahead | true | boolean |
Move the highlight to the option matching what the user types. |
| validationState6.0.0+ | - | 'valid', 'invalid', string |
The validation state, rendered as the is-{state} class on the toggle, with the matching feedback in the toggle's aria-describedby; 'invalid' also blocks the submit. Any custom state declared in the $form-validation-states Sass map is accepted. Picking a different value asks to drop it through onValidationStateChange. |
| value | - | string, string[], null |
The controlled value. Pair it with onChange; for the uncontrolled mode use defaultValue instead. |