ComboBox

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

Import


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

Appearance

Property	Type	Description
`variant`	`-`	The available variants of this component.
`size`	`-`	The available sizes of this component.

Props

ComboBox

Property	Type	Default	Description
`label`	`ReactNode`	`-`	The label text. If you don't want to visually display a label, provide an `aria-label` or `aria-labelledby` attribute for accessibility.
`placeholder`	`string`	`none`	Set the placeholder for the select.
`defaultValue`	`string`	`-`	The value of the input (uncontrolled).
`value`	`string`	`-`	The value of the input (controlled).
`defaultItems`	`Iterable<object>`	`-`	The list of suggestions (uncontrolled).
`items`	`Iterable<object>`	`-`	The list of suggestions (controlled).
`description`	`ReactNode`	`-`	A helpful text.
`errorMessage`	`ReactNode`	`-`	An error message.
`error`	`boolean`	`false`	If `true`, the field is considered invalid and if set the `errorMessage` is shown instead of the `description`.
`disabled`	`boolean`	`false`	If `true`, the input is disabled.
`disabledKeys`	`Iterable<Key>`	`-`	Suggestions that are disabled. Items cannot be selected, focused, or otherwise interacted with.
`required`	`boolean`	`false`	If `true`, the input is required
`readOnly`	`boolean`	`false`	If `true`, the input is readOnly.
`width`	`string \| number`	`full`	Sets the width of the field. You can see allowed tokens here: https://tailwindcss.com/docs/width
`menuTrigger`	`"focus"\| "input" \| "manual"`	`input`	Set which interaction shows the menu.
`autoFocus`	`boolean`	`-`	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.

ComboBox.Item

Property	Type	Default	Description
`id`	`string`	`-`	The idenfitier of the item must be unique.

Examples

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.

Preview

Code

Animals

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.

Preview

Code

Star Wars Character Lookup

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.

Preview

Code

Animals