A text-field that allows the user to select values from a provided items array.

The <ComboBox> component combines a text input with a listbox, allowing users to filter a list of options to items matching a query or adding a new value.

Its purpose is to make interaction with software more intuitive by presenting options in a concise, readable manner instead of requiring users to remember cryptic commands or navigate through complex hierarchies



To import the component you just have to use this code below.

import { ComboBox } from '@marigold/components';


variant-The available variants of this component.
size-The available sizes of this component.


labelReactNode-The label text. If you don't want to visually display a label, provide an `aria-label` or `aria-labelledby` attribute for accessibility.
placeholderstringnoneSet the placeholder for the select.
defaultValuestring-The value of the input (uncontrolled).
valuestring-The value of the input (controlled).
defaultItemsIterable<object>-The list of suggestions (uncontrolled).
itemsIterable<object>-The list of suggestions (controlled).
descriptionReactNode-A helpful text.
errorMessageReactNode-An error message.
errorbooleanfalseIf `true`, the field is considered invalid and if set the `errorMessage` is shown instead of the `description`.
disabledbooleanfalseIf `true`, the input is disabled.
disabledKeysIterable<Key>-Suggestions that are disabled. Items cannot be selected, focused, or otherwise interacted with.
requiredbooleanfalseIf `true`, the input is required
readOnlybooleanfalseIf `true`, the input is readOnly.
widthstring | numberfullSets the width of the field. You can see allowed tokens here:
menuTrigger"focus"| "input" | "manual"inputSet which interaction shows the menu.
autoFocusboolean-Whether the element should receive focus on render.
onOpenChange(isOpen: boolean, menuTrigger?: "focus"| "input" | "manual") => void-Called when the open state of the menu changes. Returns the new open state and the action that caused the opening of the menu.
onSelectionChange(key: Key) => any-Called when the selection changes.
onChange(value: string) => void-Called when the input value changes.

Item props

idstring-The idenfitier of the item must be unique.


Controlled Usage with custom Filter

If you want to listen or act while the user is typing into the ComboBox field, you can switch to controlled mode by adding an onChange handler and setting the value manually.

This is especially helpful if you need to customize the filtering. For example, you may only want to show suggestions when the user has typed at least two characters. Furthermore, you can improve the matching, as shown in the example below. In the demo, the user would not receive a suggestion if they typed "ssp" without the custom filter.

currentValue: ""

Working with asynchronous Data

The ComboBox component supports working with asynchronous data. In the example below, the useAsyncList hook is used to handle the loading and filtering of data from the server.

Displaying Suggestions

Opening the suggestion popover can be triggered through various interactions. This behavior can be adjusted by the menuTrigger prop:

  • input (default): Open when the user edits the input text.
  • focus: Open when the user focuses the <ComboBox> input.
  • manual: Open when the user presses the trigger button or uses the arrow keys.

The below examples will display the suggestions when the input field is focused.