Combobox

If your project doesn't have Wisty UI's theme yet, add it once with npx shadcn@latest add @wisty/cosmos. Until then, components keep shadcn's default look. Installation has the details.

Pass the options to Combobox as items, and render one ComboboxItem per option from a function inside ComboboxList. A function as children needs a client component, so mark the file "use client".

ComboboxInput has a chevron button that opens the list; showTrigger={false} removes it. showClear adds a clear button, which takes the chevron's place while the field has a value.

For several values, pass multiple to Combobox and build the field from chips. Call useComboboxAnchor() and give its ref to ComboboxChips as ref and to ComboboxContent as anchor, so the list opens below the whole field, as the Multiple example shows. Each ComboboxChip has a remove button unless you pass showRemove={false}.

For groups, pass items as groups that each hold their own items. The function inside ComboboxList then returns a ComboboxGroup per group, given that group's items, and a function inside its ComboboxCollection returns the options, as the Groups example shows.

onValueChange gets the new value, or null when the field is cleared. For object items, give Combobox an itemToStringLabel so the field shows a label.

In Radix projects, Combobox is built on @base-ui/react, as shadcn's is, so installing it adds that package beside radix-ui. The two work side by side.

Combobox draws SLDS's autocomplete combobox. It runs on Base UI's combobox in Radix projects too, so installing it in a Radix project adds @base-ui/react.

• ComboboxInput is slds-combobox__input in slds-input-has-icon_right, with the chevron as the input icon. Its clear button is SLDS's input icon button.
• ComboboxContent is slds-dropdown slds-dropdown_fluid slds-dropdown_length-with-icon-7, as Select's list.
• ComboboxItem is slds-listbox__option slds-listbox__option_plain, with SLDS's check column on the left.
• ComboboxLabel is slds-listbox__option-header, and ComboboxSeparator is slds-has-divider_top-space. ComboboxEmpty is a plain option row in muted text, since SLDS has no "no results" row.
• ComboboxChips is SLDS's inline listbox of pills (slds-has-inline-listbox, slds-listbox_inline), and ComboboxChip is a slds-pill option.

Known gaps:

• SLDS's autocomplete shows a search icon. Here the field has a chevron, which SLDS 2's combobox anatomy also names.
• SLDS 2 shows several values as pills below the field. Here they sit inside it, as in SLDS's inline listbox.
• Option icons, metadata lines, a loading spinner and the 5 and 10 row list heights aren't drawn. For records with icons and meta lines, use Lookup.

Inside a Dialog, Sheet, Alert dialog or Popover, the first Escape closes only the list and the next closes the dialog. On a closed field with a value, Escape clears it; in Radix projects the same Escape also closes the dialog.

• Name the input: a FieldLabel whose htmlFor matches the input's id, or aria-label.
• For an error, set aria-invalid on ComboboxInput and point aria-describedby at the message, as the States example does.
• The chevron, clear and chip remove buttons are out of the Tab order and named "Show options", "Clear" and "Remove". No prop changes those names, so for another language, edit them in your copy of the file.
• While the list is open, everything outside the field and the list is hidden from screen readers, the label and error included. The input keeps its name from the label.
• ComboboxEmpty is a status, so screen readers announce it when nothing matches. Always include one.
• In Cosmos dark, the invalid field's text reaches about 4.3:1, below WCAG AA's 4.5:1. Salesforce's own stylesheet fails the same way.

• The field fills its container. The list is as wide as the field, shows seven rows, then scrolls, and opens above the field when there's no room below.
• Chips wrap onto more rows as the field fills, and the input keeps at least 4rem.
• Long option labels wrap in the list. A long value in the field scrolls with the text.

• Filtering runs over items on every keystroke. A few hundred items are fine.
• For thousands, or for records on a server, filter yourself: pass filteredItems or control inputValue, and fetch as people type.

• Disable with disabled on both Combobox and ComboboxInput, as the States example does.
• Don't add your own Escape or outside-click handling inside a dialog. The dialogs already leave Escape to an open list.