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.
| 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.
import { Autocomplete } from '@marigold/components';export default () => { return ( <Autocomplete label="Search support tickets:" description="Type to search your recent support tickets" > <Autocomplete.Option id="ticket-1001"> [#1001] Login issues </Autocomplete.Option> <Autocomplete.Option id="ticket-1002"> [#1002] Payment failed </Autocomplete.Option> <Autocomplete.Option id="ticket-1003"> [#1003] Account verification </Autocomplete.Option> <Autocomplete.Option id="ticket-1004"> [#1004] Feature request </Autocomplete.Option> <Autocomplete.Option id="ticket-1005"> [#1005] Password reset </Autocomplete.Option> <Autocomplete.Option id="ticket-1006"> [#1006] API integration </Autocomplete.Option> <Autocomplete.Option id="ticket-1007"> [#1007] Billing inquiry </Autocomplete.Option> <Autocomplete.Option id="ticket-1008"> [#1008] Mobile app crash </Autocomplete.Option> </Autocomplete> );};<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.
Use a clear and concise text label to clarify the meaning.
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.
Keep the description of the options as short as possible to improve readability.
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.
import { Key, useState } from 'react';import { Autocomplete, SectionMessage, Stack, Table, useAsyncList,} from '@marigold/components';export default () => { const [result, setResult] = useState<{ [key: string]: string }[] | null>( null ); const list = useAsyncList<{ [key: string]: string }>({ async load({ signal, filterText }) { const res = await fetch( `https://swapi.py4e.com/api/people/?search=${filterText}`, { signal, } ); const json = await res.json(); return { items: json.results, }; }, }); const handleSubmit = (key: Key | null, value: string | null) => { if (key) { const result = list.items.find(c => c.name === key); setResult(result ? [result] : null); } if (value) { setResult(list.items); } }; return ( <Stack space={5}> <Autocomplete label="Star Wars Character" menuTrigger="focus" items={list.items} value={list.filterText} onChange={list.setFilterText} onSubmit={handleSubmit} > {(item: any) => ( <Autocomplete.Option id={item.name}>{item.name}</Autocomplete.Option> )} </Autocomplete> {result === null ? null : result.length > 0 ? ( <Table aria-label="Character results" selectionMode="none"> <Table.Header> <Table.Column rowHeader>Name</Table.Column> <Table.Column>Gender</Table.Column> <Table.Column>Skin Color</Table.Column> <Table.Column>Height</Table.Column> <Table.Column>Weight</Table.Column> </Table.Header> <Table.Body items={result}> {item => ( <Table.Row key={item.name} id={item.name}> <Table.Cell>{item.name}</Table.Cell> <Table.Cell>{item.gender}</Table.Cell> <Table.Cell>{item.skin_color}</Table.Cell> <Table.Cell>{item.height}</Table.Cell> <Table.Cell>{item.mass}</Table.Cell> </Table.Row> )} </Table.Body> </Table> ) : ( <SectionMessage> <SectionMessage.Title>Empty Result</SectionMessage.Title> <SectionMessage.Content> No Character matched your query, sorry! 😭 </SectionMessage.Content> </SectionMessage> )} </Stack> );};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.
import { Autocomplete } from '@marigold/components';export default () => ( <Autocomplete label="Genres" width="fit"> {options.map(item => ( <Autocomplete.Section key={item.category} header={item.category}> {item.genres.map(genre => ( <Autocomplete.Option key={genre}>{genre}</Autocomplete.Option> ))} </Autocomplete.Section> ))} </Autocomplete>);const options = [ { category: 'Pop and Dance', genres: [ 'Pop', 'Synth-pop', 'Electropop', 'Dance-pop', 'Teen pop', 'Disco', ], }, { category: 'Rock and Alternative', genres: [ 'Rock', 'Hard rock', 'Punk rock', 'Alternative rock', 'Indie rock', 'Grunge', 'Psychedelic rock', ], }, { category: 'Hip-Hop and R&B', genres: ['Hip-Hop', 'Rap', 'Trap', 'R&B', 'Neo-soul'], }, { category: 'Electronic and Experimental', genres: ['EDM', 'House', 'Techno', 'Dubstep', 'Ambient', 'Industrial'], }, { category: 'Jazz and Blues', genres: [ 'Jazz', 'Smooth jazz', 'Bebop', 'Blues', 'Delta blues', 'Chicago blues', ], }, { category: 'Classical and Orchestral', genres: ['Classical', 'Baroque', 'Opera', 'Symphony', 'Chamber music'], }, { category: 'Folk and Country', genres: ['Folk', 'Country', 'Bluegrass', 'Americana'], }, { category: 'Latin and World', genres: ['Reggaeton', 'Salsa', 'Bossa Nova', 'Flamenco', 'Afrobeats'], }, { category: 'Metal and Hard Music', genres: ['Heavy metal', 'Thrash metal', 'Death metal', 'Doom metal'], }, { category: 'Reggae and Caribbean', genres: ['Reggae', 'Ska', 'Dancehall', 'Soca'], },];Props
Autocomplete
Prop
Type
Autocomplete.Option
Prop
Type
Autocomplete.Section
Prop
Type
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.