Combobox

When to useLink to "When to use"

• A long list where typing is faster than scrolling: countries, fonts, tables, people.
• Results from a server as people type.
• Free text with suggestions (allowCustom): tags, labels.

Use something else when:

• there are only a handful of options and no need to type: Select
• people search for commands or places to go: the CommandPalette
• the text is free and needs no suggestions: TextField

UsageLink to "Usage"

import { Combobox } from "@arshad-shah/cynosure";

<Combobox label="Fruit" options={fruits} name="fruit" required />

By default an option matches when its label contains the typed text, ignoring case. Pass filter to match your way. While people type, the text is marked where it appears in each label (HighlightedText); options are still named by their whole label.

Options from a serverLink to "Options from a server"

Control the text with inputValue and onInputChange, fetch, and pass the results as options with filter={false}. While loading, the list says so. Focus never leaves the input, so results arriving late never swallow keystrokes; the first enabled result becomes active.

const [query, setQuery] = useState("");
const { data, isLoading } = useSearch(query);

<Combobox
  label="User"
  options={data}
  inputValue={query}
  onInputChange={setQuery}
  filter={false}
  loading={isLoading}
/>

Trailing text, dimmed options and a footer actionLink to "Trailing text, dimmed options and a footer action"

An option's trailing is drawn at the end of its row, smaller and muted (a shortcut, a count). dimmed draws an option muted while it stays choosable. footer pins an action under the options, { label, icon?, onSelect }, whatever the text matches: it is the last stop of the arrow keys, and Enter or a press closes the list and runs it. Focus stays in the input and the value does not change.

Coloured iconsLink to "Coloured icons"

iconTone and iconColor colour an option's icon and mean what Icon's tone and color mean: iconTone is a semantic colour (accent, neutral, danger, success, warning, info, muted), iconColor is any CSS colour and overrides it (brand draws a brand mark in its owner's colour). The active and the selected option keep the colour. A disabled option shows its icon without the colour, muted with the rest of the row. The input itself shows text only: iconStart is the field's own icon.

PropsLink to "Props"

Behaviour and accessibilityLink to "Behaviour and accessibility"

• Roles: the input is role="combobox" with aria-expanded, aria-controls, aria-autocomplete and aria-activedescendant; the popup is a listbox of options.
• Leaving the field: text that matches no option goes back to the last choice (unless allowCustom); an empty field clears the value.
• Forms: with name, the chosen value is submitted. With required, a blocked submit focuses the input and shows labels.required. Reset restores the default.
• Layers: the list is in the top layer, so it works inside a Dialog. Escape closes one thing at a time: the list, then the text, then the dialog.

TouchLink to "Touch"

Option rows are at least 44px tall on coarse pointers.

ThemingLink to "Theming"

Tokens: --cy-combobox-list-max-height, --cy-combobox-list-max-width, --cy-combobox-list-bg and --cy-combobox-option-active-bg. The input uses the TextField tokens. The list is an OptionList: these tokens set its --cy-option-list-* tokens.

RelatedLink to "Related"

Select · TextField · OptionList · SearchField