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
Usage
Import
To import the component you just have to use this code below.
import { ComboBox } from '@marigold/components';Appearance
Sorry! There are currently no variants and sizes available.
Props
| 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. |
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. |
Item props
| 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.
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.