Design Tokens for Mesh have just been released!
Skip to content

Autocomplete

Autocomplete allows a user to select one option from a large number of mutually exclusive choices. It is suitable for use when the list of available options is larger than 8, as it displays a filtered shortlist of up to 5 matching options when the user begins to type input. For accessibility purposes autocomplete is preferred over simply showing a dropdown of choices. If the options available to select from is less than 6, use the RadioGroup component. Situations with 6-9 available options should be assessed on a case-by-case basis.

Installation

bash
npm install @nib/autocomplete

Note: You will also need to install the peerDependencies @nib/icons and @nib-components/theme.

Usage

jsx
import Autocomplete from '@nib/autocomplete';

Interactive demo

jsx

Props

PropTypeDefaultDescription
options (required)boolean or objectfalseAn array of items. Each item must be an object with a value and text key. Additional keys can also be specified and included in the search via the keys prop.
onChange (required)functionA function to call when the input is changed. Likely being passed down by formik or redux-form.
maxOptionsDisplayednumber5The maximum number of matches to display in the menu.
keysarray['value', 'text']An array of keys to search across. Useful for capturing searches for common aliases to the options you support. When specifing other keys, the defaults are completely replaced. Be sure to include them manually if still desired.
suggestionsarrayAn array of suggested items to display initially after the user has focused the input, but before they have typed anthing. If not set, the first few options are displayed. Useful for displaying the most popular options to users.
suggestionsTitlestringSuggestedThis props helps to pass the custom suggestionList title.
onFocusfunctionA function to call when the input is focused. Likely being passed down by formik or redux-form.
onBlurfunctionA function to call when the input is blurred. Likely being passed down by formik or redux-form.
isEmptyAndOptionalbooleanfalseWhen true is passed in this will hide the validation tick icon, if passed false it will assume either the field isn't optional or is optional but not empty so field will be either valid or invalid.

In addition to these props, Autocomplete includes our FormControl and therefore expects all the same props to be supplied.

Considerations

This component is built using Downshift. Be sure to check out their comprehensive documentation for more information.

Do not wrap this component in a <FormControl>

This component has our FormControl component baked-in as downshift needs to be able to set the appropriate aria-attributes and id's on the label and other form elements.

The Autocomplete field requires a label to be provided. Ensure the label is descriptive enough to indicate the context of the input required from the user.

Autocomplete provides an option to include help text, which can be used to provide additional context if necessary.

Autocomplete displays a dynamic shortlist of filtered options once the user starts typing. This shortlist updates as the user continues to type, showing up to 5 matches using the open-source package match-sorter. For more information on the way the matched items are ordered, see their ranking system.