Autocomplete
The <Autocomplete> component is a form element with an associated popup that enables users to select a value from a collection of suggested values. Uusers may either select one of the suggestions from the popup or type a value.
Suggestions are represented by the <Autocomplete.Item> component that must be used as children of the <Autocomplete> component.
Import
import { Autocomplete } from '@marigold/components';Apperance
Sorry! There are currently no variants and sizes available.
Props
Autocomplete
| 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. |
onChange | (value: string) => void | - | Called when the input value changes. |
onSubmit | (id: string | number | null, value: string | null) => void | - | Handler that is called when the SearchAutocomplete is submitted. A "id" will be passed if the submission is a selected item (e.g. a user clicks or presses enter on an option). If the input is a custom "value", "id" will be "null". A "value" will be passed if the submission is a custom value (e.g. a user types then presses enter). If the input is a selected item, "value" will be "null". |
onClear | () => void | - | Called when the clear button is pressed. |
Autocomplete.Item
| Property | Type | Default | Description |
|---|---|---|---|
id | string | - | The idenfitier of the item. Must be unique. |
Examples
Uncontrolled Usage
The following example shows how to use the Autocomplete component in an uncontrolled manner. States, such as the user typing into the input or updating the suggestions, are automatically handled by the component. The onSubmit handler will be called when the user chooses a suggestion or submits their custom value.
User subbmitted: ""
Controlled Usage with custom Filter
If you want to listen or act while the user is typing into the Autocomplete 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.
User input: ""
User subbmitted: ""
Working with asynchronous Data
The Autocomplete 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.