Combobox

An autocomplete input with search and selection capabilities, supporting single and multi-select modes.

CMSPayload CMS Integration

Combobox options can be configured through CMS fields, allowing content editors to define searchable option lists for country selectors, tag inputs, and other filtered lists.

CMS Demo

See how content editors configure combobox options in a CMS:

Country

CMS FieldsEN

Label

Placeholder

Empty Message

Options (6)

United StatesCanadaUnited KingdomGermanyFranceJapan

Required

Disabled

Show Clear

This simulates how a content editor configures searchable dropdowns in Payload CMS. Options can be managed through an array field.

CMS ConfigurationSimulates Payload CMS combobox configuration with localization

Payload Block Example

// In your Payload CMS block config
export const CountrySelector = {
  slug: "country-selector",
  fields: [
    { name: "label", type: "text", localized: true },
    { name: "placeholder", type: "text", localized: true },
    {
      name: "options",
      type: "array",
      fields: [
        { name: "value", type: "text", required: true },
        { name: "label", type: "text", localized: true, required: true },
      ],
    },
    { name: "allowMultiple", type: "checkbox" },
  ],
}

Rendering the Block

import {
  Combobox,
  ComboboxInput,
  ComboboxContent,
  ComboboxList,
  ComboboxItem,
  ComboboxEmpty,
} from "@mordecai-design-system/ui"

export function CountryField({ data }) {
  return (
    <Combobox>
      <ComboboxInput placeholder={data.placeholder} showClear />
      <ComboboxContent>
        <ComboboxList>
          {data.options.map((opt) => (
            <ComboboxItem key={opt.value} value={opt.value}>
              {opt.label}
            </ComboboxItem>
          ))}
        </ComboboxList>
        <ComboboxEmpty>No countries found</ComboboxEmpty>
      </ComboboxContent>
    </Combobox>
  )
}

Basic Usage

ComboboxA searchable select with autocomplete

Installation

pnpm add @corew500/ui

Usage

import {
  Combobox,
  ComboboxInput,
  ComboboxContent,
  ComboboxList,
  ComboboxItem,
  ComboboxEmpty,
} from "@mordecai-design-system/ui"

<Combobox>
  <ComboboxInput placeholder="Search..." showClear />
  <ComboboxContent>
    <ComboboxList>
      <ComboboxItem value="apple">Apple</ComboboxItem>
      <ComboboxItem value="banana">Banana</ComboboxItem>
      <ComboboxItem value="cherry">Cherry</ComboboxItem>
    </ComboboxList>
    <ComboboxEmpty>No results found</ComboboxEmpty>
  </ComboboxContent>
</Combobox>

Examples

With Groups

<Combobox>
  <ComboboxInput placeholder="Select a fruit..." />
  <ComboboxContent>
    <ComboboxList>
      <ComboboxGroup>
        <ComboboxLabel>Citrus</ComboboxLabel>
        <ComboboxItem value="orange">Orange</ComboboxItem>
        <ComboboxItem value="lemon">Lemon</ComboboxItem>
      </ComboboxGroup>
      <ComboboxSeparator />
      <ComboboxGroup>
        <ComboboxLabel>Berries</ComboboxLabel>
        <ComboboxItem value="strawberry">Strawberry</ComboboxItem>
        <ComboboxItem value="blueberry">Blueberry</ComboboxItem>
      </ComboboxGroup>
    </ComboboxList>
  </ComboboxContent>
</Combobox>

Multi-Select with Chips

const anchorRef = useComboboxAnchor()

<Combobox multiple>
  <ComboboxChips ref={anchorRef}>
    {(value) => (
      <>
        {value.map((item) => (
          <ComboboxChip key={item.value} value={item.value}>
            {item.label}
          </ComboboxChip>
        ))}
        <ComboboxChipsInput placeholder="Add tags..." />
      </>
    )}
  </ComboboxChips>
  <ComboboxContent anchor={anchorRef}>
    <ComboboxList>
      <ComboboxItem value="react">React</ComboboxItem>
      <ComboboxItem value="vue">Vue</ComboboxItem>
      <ComboboxItem value="svelte">Svelte</ComboboxItem>
    </ComboboxList>
  </ComboboxContent>
</Combobox>

With Clear Button

<Combobox>
  <ComboboxInput placeholder="Search..." showClear />
  <ComboboxContent>
    <ComboboxList>...</ComboboxList>
  </ComboboxContent>
</Combobox>

Sub-components

| Component | Description | |-----------|-------------| | Combobox | Root component wrapping the combobox | | ComboboxInput | Text input with autocomplete | | ComboboxContent | Dropdown container | | ComboboxList | Scrollable list of options | | ComboboxItem | Selectable option | | ComboboxGroup | Group of related options | | ComboboxLabel | Group label | | ComboboxEmpty | Empty state when no results | | ComboboxSeparator | Visual divider between groups | | ComboboxChips | Container for multi-select chips | | ComboboxChip | Individual chip for selected value | | ComboboxChipsInput | Input inside chips container |

Props

Combobox

Prop	Type	Default	Description
`name`	string	—	Identifies the field when a form is submitted.
`id`	string	—	The id of the component.
`required`	enum	`false`	Whether the user must choose a value before submitting a form.
`readOnly`	enum	`false`	Whether the user should be unable to choose a different option from the popup.
`disabled`	enum	`false`	Whether the component should ignore user interaction.
`defaultOpen`	enum	`false`	Whether the popup is initially open. To render a controlled popup, use the `open` prop instead.
`open`	enum	—	Whether the popup is currently open. Use when controlled.
`onOpenChangeComplete`	(open: boolean) => void	—	Event handler called after any animations complete when the popup is opened or closed.
`openOnInputClick`	enum	`true`	Whether the popup opens when clicking the input.
`loopFocus`	enum	`true`	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>.
`inputValue`	enum	—	The input value of the combobox. Use when controlled.
`defaultInputValue`	enum	—	The uncontrolled input value when initially rendered. To render a controlled input, use the `inputValue` prop instead.
`inputRef`	enum	—	A ref to the hidden input element.
`grid`	enum	`false`	Whether list items are presented in a grid layout. When enabled, arrow keys navigate across rows and columns inferred from DOM rows.
`items`	enum	—	The items to be displayed in the list. Can be either a flat array of items or an array of groups with items.
`filteredItems`	enum	—	Filtered items to display in the list. When provided, the list will use these items instead of filtering the `items` prop internally. Use when you want to control filtering logic externally with the `useFilter()` hook.
`filter`	(itemValue: Value, query: string, itemToString?: (itemValue: Value) => string) => boolean	—	Filter function used to match items vs input query.
`virtualized`	enum	`false`	Whether the items are being externally virtualized.
`inline`	enum	`false`	Whether the list is rendered inline without using the popup.
`modal`	enum	`false`	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.
`limit`	number	`-1`	The maximum number of items to display in the list.
`locale`	enum	—	The locale to use for string comparison. Defaults to the user's runtime locale.
`multiple`	enum	`false`	Whether multiple items can be selected.
`autoHighlight`	enum	`false`	Whether the first matching item is highlighted automatically while filtering.
`highlightItemOnHover`	enum	`true`	Whether moving the pointer over items should highlight them. Disabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state.
`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.
`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.
`isItemEqualToValue`	(itemValue: Value, selectedValue: 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. Defaults to `Object.is` comparison.
`defaultValue`	ComboboxValueType<Value, Multiple>	—	The uncontrolled selected value of the combobox when it's initially rendered. To render a controlled combobox, use the `value` prop instead.
`actionsRef`	RefObject<Actions>	—	A ref to imperative actions. - `unmount`: When specified, the combobox will not be unmounted when closed. Instead, the `unmount` function must be called to unmount the combobox manually. Useful when the combobox's animation is controlled by an external library.
`onOpenChange`	(open: boolean, eventDetails: ChangeEventDetails) => void	—	Event handler called when the popup is opened or closed.
`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. - `'none'`: the highlight changed programmatically.
`value`	ComboboxValueType<Value, Multiple>	—	The selected value of the combobox. Use when controlled.
`onValueChange`	(value: ComboboxValueType<Value, Multiple> \| (Multiple extends true ? never : null), eventDetails: ChangeEventDetails) => void	—	Event handler called when the selected value of the combobox changes.

ComboboxInput

Prop	Type	Default	Description
`disabled`	enum	`false`	Whether the component should ignore user interaction.
`style`	enum	—	Style applied to the element, or a function that returns a style object based on the component’s state.
`className`	enum	—	CSS class applied to the element, or a function that returns a class based on the component’s state.
`render`	enum	—	Allows you to replace the component’s HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
`showTrigger`	enum	`true`	Whether to show the dropdown trigger button.
`showClear`	enum	`false`	Whether to show the clear button when a value is selected.

ComboboxContent

Prop	Type	Default	Description
`initialFocus`	enum	—	Determines the element to focus when the popup is opened. - `false`: Do not move focus. - `true`: Move focus based on the default behavior (first tabbable element or popup). - `RefObject`: Move focus to the ref element. - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`). Return an element to focus, `true` to use the default behavior, or `false`/`undefined` to do nothing.
`finalFocus`	enum	—	Determines the element to focus when the popup is closed. - `false`: Do not move focus. - `true`: Move focus based on the default behavior (trigger or previously focused element). - `RefObject`: Move focus to the ref element. - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`). Return an element to focus, `true` to use the default behavior, or `false`/`undefined` to do nothing.
`style`	enum	—	Style applied to the element, or a function that returns a style object based on the component’s state.
`className`	enum	—	CSS class applied to the element, or a function that returns a class based on the component’s state.
`render`	enum	—	Allows you to replace the component’s HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
`side`	enum	`bottom`	Which side of the anchor element to align the popup against. May automatically change to avoid collisions.
`align`	enum	`start`	How to align the popup relative to the specified side.
`sideOffset`	enum	`6`	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. The function takes a `data` object parameter with the following properties: - `data.anchor`: the dimensions of the anchor element with properties `width` and `height`. - `data.positioner`: the dimensions of the positioner element with properties `width` and `height`. - `data.side`: which side of the anchor element the positioner is aligned against. - `data.align`: how the positioner is aligned relative to the specified side. @example ```jsx <Positioner sideOffset={({ side, align, anchor, positioner }) => { return side === 'top' \|\| side === 'bottom' ? anchor.height : anchor.width; }} /> ```
`alignOffset`	enum	`0`	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. The function takes a `data` object parameter with the following properties: - `data.anchor`: the dimensions of the anchor element with properties `width` and `height`. - `data.positioner`: the dimensions of the positioner element with properties `width` and `height`. - `data.side`: which side of the anchor element the positioner is aligned against. - `data.align`: how the positioner is aligned relative to the specified side. @example ```jsx <Positioner alignOffset={({ side, align, anchor, positioner }) => { return side === 'top' \|\| side === 'bottom' ? anchor.width : anchor.height; }} /> ```
`anchor`	enum	—	An element to position the popup against. By default, the popup will be positioned against the trigger.

ComboboxItem

Prop	Type	Default	Description
`onClick`	MouseEventHandler<HTMLElement>	—	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.
`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.
`value`	any	`null`	A unique value that identifies this item.
`disabled`	enum	`false`	Whether the component should ignore user interaction.
`nativeButton`	enum	`false`	Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button.
`style`	enum	—	Style applied to the element, or a function that returns a style object based on the component’s state.
`className`	enum	—	CSS class applied to the element, or a function that returns a class based on the component’s state.
`render`	enum	—	Allows you to replace the component’s HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.

ComboboxChip

Prop	Type	Default	Description
`style`	enum	—	Style applied to the element, or a function that returns a style object based on the component’s state.
`className`	enum	—	CSS class applied to the element, or a function that returns a class based on the component’s state.
`render`	enum	—	Allows you to replace the component’s HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
`showRemove`	enum	`true`	Whether to show the remove button.