Combobox

A text input that filters a list of options as the user types, for picking one or several values from a long list.

@zenoxai/ui/components/comboboxBase UI Markdown

function ComboboxDemo() {
  const assets = [
    "web-prod-01",
    "web-prod-02",
    "db-primary",
    "db-replica",
    "vpn-gateway",
    "mail-relay",
    "build-runner-03",
  ]

  return (
    <Combobox items={assets}>
      <ComboboxInput placeholder="Search assets" aria-label="Asset" />
      <ComboboxContent>
        <ComboboxEmpty>No assets found.</ComboboxEmpty>
        <ComboboxList>
          {(asset: string) => (
            <ComboboxItem key={asset} value={asset}>
              {asset}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  )
}

Usage

import {
  Combobox,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
} from "@zenoxai/ui/components/combobox"

const assets = ["web-prod-01", "db-primary", "vpn-gateway"]

<Combobox items={assets}>
  <ComboboxInput placeholder="Search assets" aria-label="Asset" />
  <ComboboxContent>
    <ComboboxEmpty>No assets found.</ComboboxEmpty>
    <ComboboxList>
      {(asset: string) => (
        <ComboboxItem key={asset} value={asset}>
          {asset}
        </ComboboxItem>
      )}
    </ComboboxList>
  </ComboboxContent>
</Combobox>

Pass every option to Combobox as items and render them with a function inside ComboboxList. The combobox filters the list as the user types and calls the function only for the matching items. ComboboxEmpty shows when nothing matches.

Use a combobox when the list is long or the user knows what to type: assets, users, countries, CVE IDs. For a short list the user scans rather than searches, use a Select. For actions rather than values, use a Command menu.

Items can be strings or objects. Objects with a label field show that label in the input and filter on it; for any other shape, pass itemToStringLabel.

ComboboxInput takes the size of an Input Group: sm (28px), default (32px) or lg (36px). The list highlights the active item with the selection colors of Select and the menus, and opens 4px below the input.

Examples

With a clear button

showClear on ComboboxInput adds a button that resets the value. It replaces the chevron while there is a value to clear.

function ComboboxWithClear() {
  const countries = [
    "Brazil",
    "Canada",
    "Germany",
    "India",
    "Japan",
    "Netherlands",
    "United Kingdom",
    "United States",
  ]

  return (
    <Combobox items={countries} defaultValue="Germany">
      <ComboboxInput
        showClear
        placeholder="Any country"
        aria-label="Source country"
      />
      <ComboboxContent>
        <ComboboxEmpty>No countries found.</ComboboxEmpty>
        <ComboboxList>
          {(country: string) => (
            <ComboboxItem key={country} value={country}>
              {country}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  )
}

Groups

Pass groups as items, each with its own items array. Render each group with ComboboxGroup, ComboboxLabel for its heading and ComboboxCollection for its items. Empty groups disappear while filtering.

function ComboboxGroups() {
  const environments = [
    {
      value: "Production",
      items: ["web-prod-01", "web-prod-02", "db-primary"],
    },
    { value: "Staging", items: ["web-staging-01", "db-staging"] },
    { value: "Corporate", items: ["vpn-gateway", "mail-relay"] },
  ]

  return (
    <Combobox items={environments}>
      <ComboboxInput placeholder="Search assets" aria-label="Asset" />
      <ComboboxContent>
        <ComboboxEmpty>No assets found.</ComboboxEmpty>
        <ComboboxList>
          {(group: (typeof environments)[number], index: number) => (
            <ComboboxGroup key={group.value} items={group.items}>
              {index > 0 && <ComboboxSeparator />}
              <ComboboxLabel>{group.value}</ComboboxLabel>
              <ComboboxCollection>
                {(asset: string) => (
                  <ComboboxItem key={asset} value={asset}>
                    {asset}
                  </ComboboxItem>
                )}
              </ComboboxCollection>
            </ComboboxGroup>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  )
}

Multiple values

With multiple, the value is an array. Render the selected values as chips with ComboboxChips, ComboboxValue and ComboboxChip, put a ComboboxChipsInput after them, and anchor the popup to the chips with useComboboxAnchor. Backspace in an empty input removes the last chip.

phishing

ransomware

function ComboboxMultiple() {
  const tags = [
    "phishing",
    "ransomware",
    "credential-theft",
    "lateral-movement",
    "exfiltration",
  ]
  const anchor = useComboboxAnchor()

  return (
    <Combobox multiple items={tags} defaultValue={["phishing", "ransomware"]}>
      <ComboboxChips ref={anchor} className="w-full max-w-xs">
        <ComboboxValue>
          {(values: string[]) => (
            <>
              {values.map((tag) => (
                <ComboboxChip key={tag}>{tag}</ComboboxChip>
              ))}
              <ComboboxChipsInput
                placeholder="Add tag"
                aria-label="Alert tags"
              />
            </>
          )}
        </ComboboxValue>
      </ComboboxChips>
      <ComboboxContent anchor={anchor}>
        <ComboboxEmpty>No tags found.</ComboboxEmpty>
        <ComboboxList>
          {(tag: string) => (
            <ComboboxItem key={tag} value={tag}>
              {tag}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  )
}

Controlled, with a label

Pass value and onValueChange. The value is the selected item itself (here an object), or null when nothing is selected. The id on ComboboxInput goes to the <input>, so a FieldLabel from Field can point at it.

function ComboboxControlled() {
  const analysts = [
    { value: "dana", label: "Dana Whitfield" },
    { value: "marcus", label: "Marcus Oyelaran" },
    { value: "priya", label: "Priya Raman" },
    { value: "tomas", label: "Tomás Lindqvist" },
  ]
  const [assignee, setAssignee] = React.useState<
    (typeof analysts)[number] | null
  >(null)

  return (
    <Field className="max-w-xs">
      <FieldLabel htmlFor="alert-assignee">Assignee</FieldLabel>
      <Combobox items={analysts} value={assignee} onValueChange={setAssignee}>
        <ComboboxInput id="alert-assignee" placeholder="Unassigned" />
        <ComboboxContent>
          <ComboboxEmpty>No analysts found.</ComboboxEmpty>
          <ComboboxList>
            {(analyst: (typeof analysts)[number]) => (
              <ComboboxItem key={analyst.value} value={analyst}>
                {analyst.label}
              </ComboboxItem>
            )}
          </ComboboxList>
        </ComboboxContent>
      </Combobox>
      <FieldDescription>
        {assignee
          ? `${assignee.label} is notified.`
          : "Nobody is notified yet."}
      </FieldDescription>
    </Field>
  )
}

Accessibility

The input has role="combobox" and needs a name: a FieldLabel with htmlFor, or aria-label.
ArrowDown opens the list and moves through it, Enter selects the highlighted item and Escape closes the list. Focus stays in the input; the highlighted item is announced through aria-activedescendant.
The chevron, clear and chip remove buttons are icon-only. They are named “Show options”, “Clear” and “Remove” by default; pass translated names with triggerLabel and clearLabel on ComboboxInput and removeLabel on ComboboxChip. Their actions are also available from the input: ArrowDown opens the list and Backspace in an empty input removes the last chip.
Keep ComboboxEmpty in every combobox, so a search with no results says so instead of showing an empty popup.

API reference

Generated from the TypeScript source. className, style and children are accepted everywhere and omitted below.

Combobox

Groups all parts of the combobox. Doesn't render its own HTML element.

Prop	Type	Default
`actionsRef`	`RefObject<Actions \| null>` A ref to imperative actions. - `unmount`: Ends the closing phase of the combobox after an externally controlled closing animation finishes. Call `preventUnmountOnClose()` in `onOpenChange` first, otherwise the combobox completes closing on its own. Whether it leaves the DOM is decided by `keepMounted` on the portal. - `close`: Closes the combobox imperatively when called.	-
`autoComplete`	`string` Provides a hint to the browser for autofill. @see https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/autocomplete	-
`autoHighlight`	`boolean` Whether the first matching item is highlighted automatically while filtering.	`false`
`defaultInputValue`	`string \| number \| readonly string[]` The uncontrolled input value when initially rendered.	-
`defaultOpen`	`boolean` Whether the popup is initially open.	`false`
`defaultValue`	`ComboboxInputValue<Value, Multiple> \| null` The uncontrolled selected value of the combobox when it's initially rendered.	-
`disabled`	`boolean` Whether the component should ignore user interaction.	`false`
`filter`	`((item: Item, query: string, itemToString?: ((item: Item) => string)) => boolean) \| null` Filter function used to match items vs input query. Receives the source item, which is the derived value's item when `items` is a `createItems()` collection, and the item itself otherwise.	-
`filteredItems`	`readonly Item[] \| readonly Group<Item>[]` Filtered items to display in the list. When provided, the list uses these items instead of filtering the `items` prop internally. When `items` is also provided, this array must preserve its flat or grouped structure. With a `createItems()` collection, pass source items rather than derived values. Nullish entries are not supported, as in `items`. Use when you want to control filtering logic externally with the `useFilter()` hook.	-
`form`	`string` Identifies the form that owns the internal input. Useful when the combobox is rendered outside the form.	-
`grid`	`boolean` Whether list items are presented in a grid layout. When enabled, arrow keys navigate across rows and columns inferred from DOM rows.	`false`
`highlightItemOnHover`	`boolean` Whether moving the pointer over items should highlight them. Disabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state.	`true`
`id`	`string` The id of the component.	-
`inline`	`boolean` Whether the list is rendered inline without using the component's own popup.	`false`
`inputRef`	`Ref<HTMLInputElement>` A ref to the hidden input element.	-
`inputValue`	`string \| number \| readonly string[]` The input value of the combobox. Use when controlled.	-
`isItemEqualToValue`	`((itemValue: Value, value: Value) => boolean)` Custom comparison logic used to determine if a combobox item value matches the current selected value. Useful when item values are objects without matching referentially. With a `createItems()` collection, both arguments are derived values. Defaults to `Object.is` comparison.	-
`items`	`readonly any[] \| readonly Group<any>[] \| ComboboxItemCollection<Item, Value>` The items to be displayed in the list. Can be a flat array of items, an array of groups with items, or a collection created by the `createItems()` function, which derives each item's selection value and label. Nullish entries are not supported: remove them from the data before passing it.	-
`itemToStringLabel`	`((itemValue: Value) => string)` When the item values are objects (`<Combobox.Item value={object}>`), this function converts the object value to a string representation for display in the input. If the shape of the object is `{ value, label }`, the label will be used automatically without needing to specify this prop. With a `createItems()` collection, this receives the derived value, and the collection's `getLabel` takes precedence for values it can resolve.	-
`itemToStringValue`	`((itemValue: Value) => string)` When the item values are objects (`<Combobox.Item value={object}>`), this function converts the object value to a string representation for form submission. If the shape of the object is `{ value, label }`, the value will be used automatically without needing to specify this prop. With a `createItems()` collection, this receives the derived value.	-
`limit`	`number` The maximum number of items to display in the list.	`-1`
`locale`	`LocalesArgument` The locale to use for string comparison. Defaults to the user's runtime locale.	-
`loopFocus`	`boolean` Whether to loop keyboard focus back to the input when the end of the list is reached while using the arrow keys. The first item can then be reached by pressing <kbd>ArrowDown</kbd> again from the input, or the last item can be reached by pressing <kbd>ArrowUp</kbd> from the input. The input is always included in the focus loop per [ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/). When disabled, focus does not move when on the last element and the user presses <kbd>ArrowDown</kbd>, or when on the first element and the user presses <kbd>ArrowUp</kbd>.	`true`
`modal`	`boolean` Determines if the popup enters a modal state when open. - `true`: user interaction is limited to the popup: document page scroll is locked and pointer interactions on outside elements are disabled. - `false`: user interaction with the rest of the document is allowed.	`false`
`multiple`	`boolean` Whether multiple items can be selected.	`false`
`name`	`string` Identifies the field when a form is submitted.	-
`onInputValueChange`	`((inputValue: string, eventDetails: ChangeEventDetails) => void)` Event handler called when the input value changes.	-
`onItemHighlighted`	`((highlightedValue: Value, eventDetails: HighlightEventDetails) => void)` Callback fired when an item is highlighted or unhighlighted. Receives the highlighted item value (or `undefined` if no item is highlighted) and event details with a `reason` property describing why the highlight changed. The `reason` can be: - `'keyboard'`: the highlight changed due to keyboard navigation. - `'pointer'`: the highlight changed due to pointer hovering. The event may be a `MouseEvent` rather than a `PointerEvent`. - `'none'`: the highlight changed for another reason, such as typing, `autoHighlight`, the item list changing, or the popup opening or closing.	-
`onOpenChange`	`((open: boolean, eventDetails: OpenChangeEventDetails) => void)` Event handler called when the popup is opened or closed.	-
`onOpenChangeComplete`	`((open: boolean) => void)` Event handler called after any animations complete when the popup is opened or closed.	-
`onValueChange`	`((value: ComboboxOutputValue<Value, Multiple> \| (Multiple extends true ? never : null), eventDetails: ChangeEventDetails) => void)` Event handler called when the selected value of the combobox changes.	-
`open`	`boolean` Whether the popup is currently open. Use when controlled.	-
`openOnInputClick`	`boolean` Whether the popup opens when clicking the input.	`true`
`readOnly`	`boolean` Whether the user should be unable to choose a different option from the popup.	`false`
`required`	`boolean` Whether the user must choose a value before submitting a form.	`false`
`value`	`ComboboxInputValue<Value, Multiple> \| null` The selected value of the combobox. Use when controlled.	-
`virtualized`	`boolean` Whether the items are being externally virtualized.	`false`

ComboboxInput

ComboboxInput is the text field of a single-value combobox, with a chevron that opens the list and an optional clear button. `className` styles the surrounding InputGroup.

Prop	Type	Default
`clearLabel`	`string` Already-translated accessible name of the clear button.	`Clear`
`disabled`	`boolean` Whether the component should ignore user interaction.	`false`
`render`	`ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, ComboboxInputState>` Allows you to replace the component's HTML element with a different tag, or compose it with another component.	-
`showClear`	`boolean` Shows an X button that clears the value. Defaults to false.	`false`
`showTrigger`	`boolean` Shows the chevron button that opens the list. Defaults to true.	`true`
`size`	`"default" \| "sm" \| "lg"` Height: `sm` 28px, `default` 32px, `lg` 36px, the sizes of InputGroup and Input. The chevron is 14px at `sm`, 16px otherwise.	`default`
`triggerLabel`	`string` Already-translated accessible name of the chevron button.	`Show options`

ComboboxContent

ComboboxContent is the popup, rendered in a portal below the input and at least as wide as it. With chips, pass the ref from useComboboxAnchor as `anchor`, so it aligns with the chips box.

Prop	Type	Default
`align`	`"center" \| "start" \| "end"` How to align the popup relative to the specified side.	`start`
`alignOffset`	`number \| OffsetFunction` Additional offset along the alignment axis in pixels. Also accepts a function that returns the offset to read the dimensions of the anchor and positioner elements, along with its side and alignment.	`0`
`anchor`	`Element \| VirtualElement \| RefObject<Element \| null> \| (() => Element \| VirtualElement \| null) \| null` An element to position the popup against. By default, the popup will be positioned against the trigger.	-
`finalFocus`	`boolean \| RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => boolean \| void \| HTMLElement \| null)` Determines the element to focus when the popup is closed.	-
`initialFocus`	`boolean \| RefObject<HTMLElement \| null> \| ((openType: InteractionType) => boolean \| void \| HTMLElement \| null)` Determines the element to focus when the popup is opened.	-
`render`	`ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, ComboboxPopupState>` Allows you to replace the component's HTML element with a different tag, or compose it with another component.	-
`side`	`"left" \| "right" \| "top" \| "bottom" \| "inline-end" \| "inline-start"` Which side of the anchor element to align the popup against. May automatically change to avoid collisions.	`bottom`
`sideOffset`	`number \| OffsetFunction` Distance between the anchor and the popup in pixels. Also accepts a function that returns the distance to read the dimensions of the anchor and positioner elements, along with its side and alignment.	`0`

ComboboxList

ComboboxList is the scrolling list of options; give it a function child that renders a ComboboxItem per filtered item.

Prop	Type	Default
`render`	`ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, ComboboxListState>` Allows you to replace the component's HTML element with a different tag, or compose it with another component.	-

ComboboxItem

Prop	Type	Default
`disabled`	`boolean` Whether the component should ignore user interaction.	`false`
`index`	`number` The index of the item in the list. Improves performance when specified by avoiding the need to calculate the index automatically from the DOM.	-
`nativeButton`	`boolean` Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`).	`true`
`onClick`	`((event: BaseUIEvent<MouseEvent<HTMLDivElement, MouseEvent>>) => void)` An optional click handler for the item when selected. It fires when clicking the item with the pointer, as well as when pressing `Enter` with the keyboard if the item is highlighted when the `Input` or `List` element has focus.	-
`render`	`ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, ComboboxItemState>` Allows you to replace the component's HTML element with a different tag, or compose it with another component.	-
`value`	`any` A unique value that identifies this item.	`null`

ComboboxGroup

Prop	Type	Default
`items`	`readonly any[]` Items to be rendered within this group. When provided, child `Collection` components will use these items.	-
`render`	`ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, ComboboxGroupState>` Allows you to replace the component's HTML element with a different tag, or compose it with another component.	-

ComboboxLabel

Prop	Type	Default
`render`	`ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, ComboboxGroupLabelState>` Allows you to replace the component's HTML element with a different tag, or compose it with another component.	-

ComboboxCollection

ComboboxCollection renders the filtered items of one ComboboxGroup through a function child; a flat list needs only the function child of ComboboxList.

No props of its own. Accepts the props of the element it renders.

ComboboxEmpty

ComboboxEmpty is the message shown when no item matches the query.

Prop	Type	Default
`render`	`ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, ComboboxEmptyState>` Allows you to replace the component's HTML element with a different tag, or compose it with another component.	-

ComboboxSeparator

Prop	Type	Default
`orientation`	`"horizontal" \| "vertical"` The orientation of the separator.	`'horizontal'`
`render`	`ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, ComboboxSeparatorState>` Allows you to replace the component's HTML element with a different tag, or compose it with another component.	-

ComboboxChips

ComboboxChips is the input box of a multiple combobox: a ComboboxChip per selected value, then a ComboboxChipsInput.

Prop	Type	Default
`render`	`ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, ComboboxChipsState>` Allows you to replace the component's HTML element with a different tag, or compose it with another component.	-

ComboboxChip

Prop	Type	Default
`removeLabel`	`string` Already-translated accessible name of the remove button.	`Remove`
`render`	`ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, ComboboxChipState>` Allows you to replace the component's HTML element with a different tag, or compose it with another component.	-
`showRemove`	`boolean` Shows the X button that removes the chip. Defaults to true.	`true`

ComboboxChipsInput

ComboboxChipsInput is the text input after the chips in ComboboxChips.

Prop	Type	Default
`disabled`	`boolean` Whether the component should ignore user interaction.	`false`
`render`	`ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, ComboboxInputState>` Allows you to replace the component's HTML element with a different tag, or compose it with another component.	-

ComboboxTrigger

ComboboxTrigger is a button with a chevron that opens the list. ComboboxInput renders one already; use it alone when the input sits inside the popup.

Prop	Type	Default
`disabled`	`boolean` Whether the component should ignore user interaction.	`false`
`nativeButton`	`boolean` Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`).	`true`
`render`	`ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, ComboboxTriggerState>` Allows you to replace the component's HTML element with a different tag, or compose it with another component.	-

ComboboxValue

ComboboxValue renders the selected value, or a function of it, such as the chips of a multiple combobox.

Prop	Type	Default
`placeholder`	`ReactNode` The placeholder value to display when no value is selected. This is overridden by `children` if specified, or by a null item's label in `items`.	-

useComboboxAnchor

useComboboxAnchor returns a ref to attach to ComboboxChips and pass as `anchor` to ComboboxContent, so the popup aligns with the chips box.

No props of its own. Accepts the props of the element it renders.