Combobox

import { Combobox } from '@yarcl/react';

With a controlled value, the input shows the selected option’s label on mount and follows changes to the value or its label, including options loaded later. Typed searches remain through option updates until selection, blur or dismissal. Changing the selected value resets the search. A controlled inputValue takes precedence over the selected label.

One component covers four modes.

Searchable select

The default. Typing filters the options; the value must be one of them. On blur, the text resets to the selected option’s label.

Country

Value: none

<Combobox options={countries} value={country} onValueChange={setCountry} placeholder="Search countries" />

Typeahead

allowCustomValue accepts any text; the options are suggestions.

Framework

Value: none

<Combobox options={frameworks} allowCustomValue onValueChange={setValue} />

Async search

Filter on the server: set filter={false}, update options from onInputValueChange, and show loading in between.

Remote search

Results arrive after 500 ms.

<Combobox
  options={results}
  filter={false}
  loading={loading}
  onInputValueChange={setQuery}
  emptyMessage="No countries found"
/>

Multiple

multiple makes the value an array. Each pick becomes a removable chip before the input; the list stays open and the input clears so you can keep going. Picking a selected option again removes it. maxSelected caps the count, and name submits one hidden input per value.

It works with the other modes: add allowCustomValue to turn typed text into a chip on Enter, or filter={false} with onInputValueChange for async search.

Countries visited

• Sweden
• Japan

Value: sweden, japan

const [visited, setVisited] = useState<string[]>([]);

<Combobox multiple options={countries} value={visited} onValueChange={setVisited} name="visited" />

Chips are Badges in the control’s size and color, with the Badge’s variant (by default defaults.softVariant). The control keeps the input height on one line and grows as chips wrap.

Keyboard

Key	Action
typing	filters and opens the list, highlighting the first match
↑ ↓	moves the highlight (focus stays in the input)
Enter	chooses the highlighted option; with multiple, toggles it
Esc	closes the list
Backspace	with multiple and an empty input, removes the last chip
← →	with multiple, at the start of the input, moves focus across the chips and back
Backspace Delete Enter	on a chip, removes it and returns focus to the input

The input has role="combobox" and points at the highlighted option with aria-activedescendant. With multiple, the listbox has aria-multiselectable and selected options have aria-selected. Chips are a list named “Selected”, and each remove button is labelled with the option, like “Remove Sweden”. Chips are not tab stops, so Tab goes straight to the input.

Part styles

Single and multiple selection popups follow shared components.Listbox.slots settings with data-part="panel" and "item". The same settings style Select popups. See component parts.

Props

Accepts every native <input> attribute except color, size, value, defaultValue, onChange and multiple.

Plus the value props, typed by multiple:

Prop	Single (default)	multiple
value	V | null	V[]
defaultValue	V | null	V[]
onValueChange	(value: V | null) => void	(value: V[]) => void
maxSelected	not allowed	number

Prop	Type	Default	Description
options required	readonly SelectOption<V>[]		The options to suggest. For async search, update this as results arrive and set filter={false}.
allowCustomValue	boolean	false	Accepts typed text that doesn't match an option (typeahead / autocomplete). When false, unchosen text is discarded on blur: the input resets to the selected option's label, or clears with multiple. With multiple, Enter adds the typed text as a chip.
color	Colorconfig	config.defaults.color	Semantic color, from the colors config.
emptyMessage	ReactNode	config.labels.noResults	Shown when no options match.
filter	boolean | (option: SelectOption<V>, text: string) => boolean	true	How options are matched against the typed text. true: case-insensitive "contains" on the label; a function for custom matching; false to show options as given (e.g. already filtered by a server).
inputValue	string		Controlled text in the input.
loading	boolean		Shows a loading row instead of options.
loadingMessage	ReactNode	config.labels.loadingResults	Shown while loading is set.
onInputValueChange	(text: string) => void		Called on every keystroke with the input text. Use it to fetch options for async search.
radius	'size' | Radiusconfig	config.defaults.radius	Border radius, from the radii config, or 'size' for the radius named like the control's size.
removeLabel	(name: string) => string	config.labels.removeItem	Accessible name of a chip removal button, given the option label.
selectedLabel	string	config.labels.selectedItems	Accessible name of the multi-select chip list.
size	'lg' | 'xs' | 'sm' | 'md' | 'xl'	config.defaults.size	Control size, from the sizes config.