Autocomplete
A searchfield that displays a dynamic list of suggestions.
The <Autocomplete> component is an input field that offers suggestions for the user's input as they type. These proposals are based on a predefined set of options.
It also helps to reduce the effort and time required to input data and to avoid errors that can occur due to typos or misspellings. The suggestions are displayed in a combobox list, and the user can select one of the options or continue typing their own input.
Anatomy
Autocomplete is made up of a form input field, label, and overlay of menu options. The label and description aren't required and may be visually hidden. The clear button is shown after typing starts.
Label: Descriptive text guiding the user on what information is required in the input field.
Input field: A text box where users can enter or edit data.
Help text: Supplementary information displayed below the input field to assist users in filling out the form correctly. Can also be an errormessage.
Clear button: A button that allows users to quickly remove all text from the input field.
Dropdown arrow: An icon indicating that more options are available; clicking it reveals a list of selectable items.
Overlay: Hold a list of all possible options which can be selected.
Appearance
The appearance of a component can be customized using the variant and size props. These props adjust the visual style and dimensions of the component, available values are based on the active theme.
Variant
Size
The selected theme does not has any options for "variant" and "size".
User subbmitted: ""
| Property | Type | Description |
|---|---|---|
variant | - | The available variants of this component. |
size | - | The available sizes of this component. |
Usage
Use an autocomplete search field (also known as a predictive search) to help users find what they’re looking for faster. An autocomplete search field displays suggestions as someone types into the field, just like the Google search bar. It is also suitable for fields where people know what they’re looking for, e.g. country of birth, a particular event, or a particular city.
Preview
Code
Type to search your recent support tickets
Type to search your recent support tickets
Do
Use an
<Autocomplete> instead of a long list.Text label
The label of the <Autocomplete> provides a clear and concise description of its purpose, making it easier for users to
interact with the interface and understand it.
Always display a label unless the <Autocomplete> is next to another component which already has a label.
Do
Use a clear and concise text label to clarify the meaning.
Don't
Avoid using the Autocomplete without a label unless the Autocomplete is part of a complex scenario and its context is already set.
Item content
Consider the width of the Autocomplete and keep the names of the options short and compact so that they fit. Long item names that occupy multiple lines are hard to perceive and should be avoided.
Do
Keep the description of the options as short as possible to improve readability.
Don't
Avoid using lengthy option descriptions because the text can get truncated and users will find it difficult to read.
Async Loading
- Large datasets that would be inefficient to load all at once
- API-backed search where results come from a server
- Dynamic filtering where options change based on input
The useAsyncListData hook provides built-in support for async loading, handling request states, cancellation, and filtering automatically. When implementing async loading.
Preview
Code
With sections
When related options are present, organizing them into sections enhances clarity and usability. Grouping options provides additional context and helps users navigate choices more easily. This approach reduces complexity and allows for additional guidance when needed, ensuring a more intuitive experience.
This can be achieved by wrapping the options in the <Autocomplete.Section> component. A header is required for each section, which is set using the header prop.
Preview
Code
Props
Did you know? You can explore, test, and customize props live in Marigold's storybook. Watch the effects they have in real-time!
Autocomplete
allowsCustomValue?boolean;
Whether the ComboBox allows a non-item matching input value to be set.
allowsEmptyCollection?boolean;
Whether the combo box allows the menu to be open when the collection is empty.
aria-describedby?string;
Identifies the element (or elements) that describes the object.
aria-details?string;
Identifies the element (or elements) that provide a detailed, extended description for the object.
aria-label?string;
Defines a string value that labels the current element.
aria-labelledby?string;
Identifies the element (or elements) that labels the current element.
autoFocus?boolean;
Whether the element should receive focus on render.
children?ChildrenOrFunction<ComboBoxRenderProps>;
The children of the component. A function may be provided to alter the children based on component state.
defaultFilter?(textValue: string, inputValue: string) => boolean;
The filter function used to determine if a option should be included in the combo box list.
defaultInputValue?string;
The default value of the ComboBox input (uncontrolled).
defaultItems?Iterable<object>;
The list of ComboBox items (uncontrolled).
defaultSelectedKey?Key;
The initial selected key in the collection (uncontrolled).
defaultValue?string;
The value of the input (uncontrolled).
description?ReactNode;
A helpful text.
dir?string;
disabled?boolean;
If
true, the input is disabled.Defaults to:
"false"disabledKeys?Iterable<Key>;
The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
error?boolean;
If
true, the field is considered invalid and if set the errorMessage is shown instead of the description.Defaults to:
"false"errorMessage?ReactNode | ((v: ValidationResult) => ReactNode);
An error message.
form?string;
The
<form> element to associate the input with.
The value of this attribute must be the id of a <form> in the same document.
See MDN.formValue?"text" | "key";
Whether the text or key of the selected item is submitted as part of an HTML form.
When
allowsCustomValue is true, this option does not apply and the text is always submitted.Defaults to:
'key'hidden?boolean;
id?string;
The element's unique identifier. See MDN.
inert?boolean;
items?Iterable<object>;
The list of ComboBox items (controlled).
label?ReactNode;
Specifies the label of the field.
lang?string;
menuTrigger?MenuTriggerAction;
The interaction required to display the ComboBox menu.
Defaults to:
'input'name?string;
The name of the input element, used when submitting an HTML form. See MDN.
onAnimationEnd?AnimationEventHandler<HTMLDivElement>;
onAnimationEndCapture?AnimationEventHandler<HTMLDivElement>;
onAnimationIteration?AnimationEventHandler<HTMLDivElement>;
onAnimationIterationCapture?AnimationEventHandler<HTMLDivElement>;
onAnimationStart?AnimationEventHandler<HTMLDivElement>;
onAnimationStartCapture?AnimationEventHandler<HTMLDivElement>;
onAuxClick?MouseEventHandler<HTMLDivElement>;
onAuxClickCapture?MouseEventHandler<HTMLDivElement>;
onBlur?(e: FocusEvent<HTMLInputElement, Element>) => void;
Handler that is called when the element loses focus.
onChange?(value: string) => void;
Called when the input value changes.
onClear?() => void;
Called when the clear button is pressed.
onClick?MouseEventHandler<HTMLDivElement>;
onClickCapture?MouseEventHandler<HTMLDivElement>;
onContextMenu?MouseEventHandler<HTMLDivElement>;
onContextMenuCapture?MouseEventHandler<HTMLDivElement>;
onDoubleClick?MouseEventHandler<HTMLDivElement>;
onDoubleClickCapture?MouseEventHandler<HTMLDivElement>;
onFocus?(e: FocusEvent<HTMLInputElement, Element>) => void;
Handler that is called when the element receives focus.
onFocusChange?(isFocused: boolean) => void;
Handler that is called when the element's focus status changes.
onGotPointerCapture?PointerEventHandler<HTMLDivElement>;
onGotPointerCaptureCapture?PointerEventHandler<HTMLDivElement>;
onKeyDown?(e: KeyboardEvent) => void;
Handler that is called when a key is pressed.
onKeyUp?(e: KeyboardEvent) => void;
Handler that is called when a key is released.
onLostPointerCapture?PointerEventHandler<HTMLDivElement>;
onLostPointerCaptureCapture?PointerEventHandler<HTMLDivElement>;
onMouseDown?MouseEventHandler<HTMLDivElement>;
onMouseDownCapture?MouseEventHandler<HTMLDivElement>;
onMouseEnter?MouseEventHandler<HTMLDivElement>;
onMouseLeave?MouseEventHandler<HTMLDivElement>;
onMouseMove?MouseEventHandler<HTMLDivElement>;
onMouseMoveCapture?MouseEventHandler<HTMLDivElement>;
onMouseOut?MouseEventHandler<HTMLDivElement>;
onMouseOutCapture?MouseEventHandler<HTMLDivElement>;
onMouseOver?MouseEventHandler<HTMLDivElement>;
onMouseOverCapture?MouseEventHandler<HTMLDivElement>;
onMouseUp?MouseEventHandler<HTMLDivElement>;
onMouseUpCapture?MouseEventHandler<HTMLDivElement>;
onOpenChange?(isOpen: boolean, menuTrigger?: MenuTriggerAction) => void;
Method that is called when the open state of the menu changes. Returns the new open state and the action that caused the opening of the menu.
onPointerCancel?PointerEventHandler<HTMLDivElement>;
onPointerCancelCapture?PointerEventHandler<HTMLDivElement>;
onPointerDown?PointerEventHandler<HTMLDivElement>;
onPointerDownCapture?PointerEventHandler<HTMLDivElement>;
onPointerEnter?PointerEventHandler<HTMLDivElement>;
onPointerLeave?PointerEventHandler<HTMLDivElement>;
onPointerMove?PointerEventHandler<HTMLDivElement>;
onPointerMoveCapture?PointerEventHandler<HTMLDivElement>;
onPointerOut?PointerEventHandler<HTMLDivElement>;
onPointerOutCapture?PointerEventHandler<HTMLDivElement>;
onPointerOver?PointerEventHandler<HTMLDivElement>;
onPointerOverCapture?PointerEventHandler<HTMLDivElement>;
onPointerUp?PointerEventHandler<HTMLDivElement>;
onPointerUpCapture?PointerEventHandler<HTMLDivElement>;
onScroll?UIEventHandler<HTMLDivElement>;
onScrollCapture?UIEventHandler<HTMLDivElement>;
onSelectionChange?(key: Key | null) => void;
Handler that is called when the selection changes.
onSubmit?(value: string | number | null, key: Key | null) => void;
Handler that is called when the SearchAutocomplete is submitted.
A
key 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, key 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.onTouchCancel?TouchEventHandler<HTMLDivElement>;
onTouchCancelCapture?TouchEventHandler<HTMLDivElement>;
onTouchEnd?TouchEventHandler<HTMLDivElement>;
onTouchEndCapture?TouchEventHandler<HTMLDivElement>;
onTouchMove?TouchEventHandler<HTMLDivElement>;
onTouchMoveCapture?TouchEventHandler<HTMLDivElement>;
onTouchStart?TouchEventHandler<HTMLDivElement>;
onTouchStartCapture?TouchEventHandler<HTMLDivElement>;
onTransitionCancel?TransitionEventHandler<HTMLDivElement>;
onTransitionCancelCapture?TransitionEventHandler<HTMLDivElement>;
onTransitionEnd?TransitionEventHandler<HTMLDivElement>;
onTransitionEndCapture?TransitionEventHandler<HTMLDivElement>;
onTransitionRun?TransitionEventHandler<HTMLDivElement>;
onTransitionRunCapture?TransitionEventHandler<HTMLDivElement>;
onTransitionStart?TransitionEventHandler<HTMLDivElement>;
onTransitionStartCapture?TransitionEventHandler<HTMLDivElement>;
onWheel?WheelEventHandler<HTMLDivElement>;
onWheelCapture?WheelEventHandler<HTMLDivElement>;
placeholder?string;
readOnly?boolean;
If
true, the input is readOnly.Defaults to:
"false"ref?Ref<HTMLInputElement>;
Allows getting a ref to the component instance.
Once the component unmounts, React will set
ref.current to null
(or call the ref with null if you passed a callback ref).
@see {@link https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom React Docs}required?boolean;
If
true, the input is required.Defaults to:
"false"selectedKey?Key | null;
The currently selected key in the collection (controlled).
shouldFocusWrap?boolean;
Whether keyboard navigation is circular.
translate?"yes" | "no";
validationBehavior?"native" | "aria";
Whether to use native HTML form validation to prevent form submission
when the value is missing or invalid, or mark the field as required
or invalid via ARIA.
Defaults to:
'native'value?string;
The value of the input (controlled).
width?WidthProp;
Sets the width of the element. You can see allowed tokens here.
Autocomplete.Option
aria-label?string;
An accessibility label for this item.
children?ReactNode;
The children of the component
dir?string;
download?string | boolean;
Causes the browser to download the linked URL. A string may be provided to suggest a file name. See MDN.
hidden?boolean;
href?string;
A URL to link to. See MDN.
hrefLang?string;
Hints at the human language of the linked URL. SeeMDN.
id?Key;
The unique id of the item.
inert?boolean;
isDisabled?boolean;
Whether the item is disabled.
lang?string;
onAction?() => void;
Handler that is called when a user performs an action on the item. The exact user event depends on
the collection's
selectionBehavior prop and the interaction modality.onAnimationEnd?AnimationEventHandler<HTMLDivElement>;
onAnimationEndCapture?AnimationEventHandler<HTMLDivElement>;
onAnimationIteration?AnimationEventHandler<HTMLDivElement>;
onAnimationIterationCapture?AnimationEventHandler<HTMLDivElement>;
onAnimationStart?AnimationEventHandler<HTMLDivElement>;
onAnimationStartCapture?AnimationEventHandler<HTMLDivElement>;
onAuxClick?MouseEventHandler<HTMLDivElement>;
onAuxClickCapture?MouseEventHandler<HTMLDivElement>;
onClick?(e: MouseEvent<FocusableElement, MouseEvent>) => void;
Not recommended – use
onPress instead. onClick is an alias for onPress
provided for compatibility with other libraries. onPress provides
additional event details for non-mouse interactions.onClickCapture?MouseEventHandler<HTMLDivElement>;
onContextMenu?MouseEventHandler<HTMLDivElement>;
onContextMenuCapture?MouseEventHandler<HTMLDivElement>;
onDoubleClick?MouseEventHandler<HTMLDivElement>;
onDoubleClickCapture?MouseEventHandler<HTMLDivElement>;
onGotPointerCapture?PointerEventHandler<HTMLDivElement>;
onGotPointerCaptureCapture?PointerEventHandler<HTMLDivElement>;
onHoverChange?(isHovering: boolean) => void;
Handler that is called when the hover state changes.
onHoverEnd?(e: HoverEvent) => void;
Handler that is called when a hover interaction ends.
onHoverStart?(e: HoverEvent) => void;
Handler that is called when a hover interaction starts.
onLostPointerCapture?PointerEventHandler<HTMLDivElement>;
onLostPointerCaptureCapture?PointerEventHandler<HTMLDivElement>;
onMouseDown?MouseEventHandler<HTMLDivElement>;
onMouseDownCapture?MouseEventHandler<HTMLDivElement>;
onMouseEnter?MouseEventHandler<HTMLDivElement>;
onMouseLeave?MouseEventHandler<HTMLDivElement>;
onMouseMove?MouseEventHandler<HTMLDivElement>;
onMouseMoveCapture?MouseEventHandler<HTMLDivElement>;
onMouseOut?MouseEventHandler<HTMLDivElement>;
onMouseOutCapture?MouseEventHandler<HTMLDivElement>;
onMouseOver?MouseEventHandler<HTMLDivElement>;
onMouseOverCapture?MouseEventHandler<HTMLDivElement>;
onMouseUp?MouseEventHandler<HTMLDivElement>;
onMouseUpCapture?MouseEventHandler<HTMLDivElement>;
onPointerCancel?PointerEventHandler<HTMLDivElement>;
onPointerCancelCapture?PointerEventHandler<HTMLDivElement>;
onPointerDown?PointerEventHandler<HTMLDivElement>;
onPointerDownCapture?PointerEventHandler<HTMLDivElement>;
onPointerEnter?PointerEventHandler<HTMLDivElement>;
onPointerLeave?PointerEventHandler<HTMLDivElement>;
onPointerMove?PointerEventHandler<HTMLDivElement>;
onPointerMoveCapture?PointerEventHandler<HTMLDivElement>;
onPointerOut?PointerEventHandler<HTMLDivElement>;
onPointerOutCapture?PointerEventHandler<HTMLDivElement>;
onPointerOver?PointerEventHandler<HTMLDivElement>;
onPointerOverCapture?PointerEventHandler<HTMLDivElement>;
onPointerUp?PointerEventHandler<HTMLDivElement>;
onPointerUpCapture?PointerEventHandler<HTMLDivElement>;
onPress?(e: PressEvent) => void;
Handler that is called when the press is released over the target.
onPressChange?(isPressed: boolean) => void;
Handler that is called when the press state changes.
onPressEnd?(e: PressEvent) => void;
Handler that is called when a press interaction ends, either
over the target or when the pointer leaves the target.
onPressStart?(e: PressEvent) => void;
Handler that is called when a press interaction starts.
onPressUp?(e: PressEvent) => void;
Handler that is called when a press is released over the target, regardless of
whether it started on the target or not.
onScroll?UIEventHandler<HTMLDivElement>;
onScrollCapture?UIEventHandler<HTMLDivElement>;
onTouchCancel?TouchEventHandler<HTMLDivElement>;
onTouchCancelCapture?TouchEventHandler<HTMLDivElement>;
onTouchEnd?TouchEventHandler<HTMLDivElement>;
onTouchEndCapture?TouchEventHandler<HTMLDivElement>;
onTouchMove?TouchEventHandler<HTMLDivElement>;
onTouchMoveCapture?TouchEventHandler<HTMLDivElement>;
onTouchStart?TouchEventHandler<HTMLDivElement>;
onTouchStartCapture?TouchEventHandler<HTMLDivElement>;
onTransitionCancel?TransitionEventHandler<HTMLDivElement>;
onTransitionCancelCapture?TransitionEventHandler<HTMLDivElement>;
onTransitionEnd?TransitionEventHandler<HTMLDivElement>;
onTransitionEndCapture?TransitionEventHandler<HTMLDivElement>;
onTransitionRun?TransitionEventHandler<HTMLDivElement>;
onTransitionRunCapture?TransitionEventHandler<HTMLDivElement>;
onTransitionStart?TransitionEventHandler<HTMLDivElement>;
onTransitionStartCapture?TransitionEventHandler<HTMLDivElement>;
onWheel?WheelEventHandler<HTMLDivElement>;
onWheelCapture?WheelEventHandler<HTMLDivElement>;
ping?string;
A space-separated list of URLs to ping when the link is followed. See MDN.
referrerPolicy?HTMLAttributeReferrerPolicy;
How much of the referrer to send when following the link. See MDN.
rel?string;
The relationship between the linked resource and the current page. See MDN.
routerOptions?undefined;
Options for the configured client side router.
target?HTMLAttributeAnchorTarget;
The target window for the link. See MDN.
textValue?string;
A string representation of the item's contents, used for features like typeahead.
translate?"yes" | "no";
value?object;
The object value that this item represents. When using dynamic collections, this is set automatically.
Autocomplete.Section
aria-label?string;
An accessibility label for the section.
childrenReactNode;
Children of the section.
dependencies?readonly any[]Values that should invalidate the item cache when using dynamic collections.
dir?string;
headerReactNode;
Section header to display.
hidden?boolean;
id?Key;
The unique id of the section.
inert?boolean;
items?Iterable<object>;
Item objects in the section.
lang?string;
onAnimationEnd?AnimationEventHandler<HTMLElement>;
onAnimationEndCapture?AnimationEventHandler<HTMLElement>;
onAnimationIteration?AnimationEventHandler<HTMLElement>;
onAnimationIterationCapture?AnimationEventHandler<HTMLElement>;
onAnimationStart?AnimationEventHandler<HTMLElement>;
onAnimationStartCapture?AnimationEventHandler<HTMLElement>;
onAuxClick?MouseEventHandler<HTMLElement>;
onAuxClickCapture?MouseEventHandler<HTMLElement>;
onClick?MouseEventHandler<HTMLElement>;
onClickCapture?MouseEventHandler<HTMLElement>;
onContextMenu?MouseEventHandler<HTMLElement>;
onContextMenuCapture?MouseEventHandler<HTMLElement>;
onDoubleClick?MouseEventHandler<HTMLElement>;
onDoubleClickCapture?MouseEventHandler<HTMLElement>;
onGotPointerCapture?PointerEventHandler<HTMLElement>;
onGotPointerCaptureCapture?PointerEventHandler<HTMLElement>;
onLostPointerCapture?PointerEventHandler<HTMLElement>;
onLostPointerCaptureCapture?PointerEventHandler<HTMLElement>;
onMouseDown?MouseEventHandler<HTMLElement>;
onMouseDownCapture?MouseEventHandler<HTMLElement>;
onMouseEnter?MouseEventHandler<HTMLElement>;
onMouseLeave?MouseEventHandler<HTMLElement>;
onMouseMove?MouseEventHandler<HTMLElement>;
onMouseMoveCapture?MouseEventHandler<HTMLElement>;
onMouseOut?MouseEventHandler<HTMLElement>;
onMouseOutCapture?MouseEventHandler<HTMLElement>;
onMouseOver?MouseEventHandler<HTMLElement>;
onMouseOverCapture?MouseEventHandler<HTMLElement>;
onMouseUp?MouseEventHandler<HTMLElement>;
onMouseUpCapture?MouseEventHandler<HTMLElement>;
onPointerCancel?PointerEventHandler<HTMLElement>;
onPointerCancelCapture?PointerEventHandler<HTMLElement>;
onPointerDown?PointerEventHandler<HTMLElement>;
onPointerDownCapture?PointerEventHandler<HTMLElement>;
onPointerEnter?PointerEventHandler<HTMLElement>;
onPointerLeave?PointerEventHandler<HTMLElement>;
onPointerMove?PointerEventHandler<HTMLElement>;
onPointerMoveCapture?PointerEventHandler<HTMLElement>;
onPointerOut?PointerEventHandler<HTMLElement>;
onPointerOutCapture?PointerEventHandler<HTMLElement>;
onPointerOver?PointerEventHandler<HTMLElement>;
onPointerOverCapture?PointerEventHandler<HTMLElement>;
onPointerUp?PointerEventHandler<HTMLElement>;
onPointerUpCapture?PointerEventHandler<HTMLElement>;
onScroll?UIEventHandler<HTMLElement>;
onScrollCapture?UIEventHandler<HTMLElement>;
onTouchCancel?TouchEventHandler<HTMLElement>;
onTouchCancelCapture?TouchEventHandler<HTMLElement>;
onTouchEnd?TouchEventHandler<HTMLElement>;
onTouchEndCapture?TouchEventHandler<HTMLElement>;
onTouchMove?TouchEventHandler<HTMLElement>;
onTouchMoveCapture?TouchEventHandler<HTMLElement>;
onTouchStart?TouchEventHandler<HTMLElement>;
onTouchStartCapture?TouchEventHandler<HTMLElement>;
onTransitionCancel?TransitionEventHandler<HTMLElement>;
onTransitionCancelCapture?TransitionEventHandler<HTMLElement>;
onTransitionEnd?TransitionEventHandler<HTMLElement>;
onTransitionEndCapture?TransitionEventHandler<HTMLElement>;
onTransitionRun?TransitionEventHandler<HTMLElement>;
onTransitionRunCapture?TransitionEventHandler<HTMLElement>;
onTransitionStart?TransitionEventHandler<HTMLElement>;
onTransitionStartCapture?TransitionEventHandler<HTMLElement>;
onWheel?WheelEventHandler<HTMLElement>;
onWheelCapture?WheelEventHandler<HTMLElement>;
translate?"yes" | "no";
value?object;
The object value that this section represents. When using dynamic collections, this is set automatically.
Alternative components
Combobox: A text field that allows the user to select values from a provided items array. Useful when there are mote than 15 options.
Radio: Component which allows to select only one option from a list. Use it if you have less than 5 options.
Select: A component with which you can choose exactly one option from a list with predefined options.
Related
Last update: a month ago