Stable

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.

GitHub, opens in a new tab·Storybook, opens in a new tab·Figma, opens in a new tab

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

<Autocomplete
  label="Favourite colour"
  help="Start typing to see options"
  error="This is required. We need to know."
  options={[
    {value: 'red', text: 'Red'},
    {value: 'blue', text: 'Blue'}
  ]}
  keys={['text', 'value']}
  suggestions={[
    {value: 'red', text: 'Red'},
    {value: 'blue', text: 'Blue'}
  ]}
  disabled={false}
  valid={false}
  validated={false}
  onChange={() => null}
/>

<Autocomplete
  label="Favourite colour"
  help="Start typing to see options"
  error="This is required. We need to know."
  options={[
    {value: 'red', text: 'Red'},
    {value: 'blue', text: 'Blue'}
  ]}
  keys={['text', 'value']}
  suggestions={[
    {value: 'red', text: 'Red'},
    {value: 'blue', text: 'Blue'}
  ]}
  disabled={false}
  valid={false}
  validated={false}
  onChange={() => null}
/>

Props

Prop	Type	Default	Description
`options` (required)	boolean or object	`false`	An 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)	function		A function to call when the input is changed. Likely being passed down by formik or redux-form.
`maxOptionsDisplayed`	number	`5`	The maximum number of matches to display in the menu.
`keys`	array	`['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.
`suggestions`	array		An 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.
`suggestionsTitle`	string	Suggested	This props helps to pass the custom suggestionList title.
`onFocus`	function		A function to call when the input is focused. Likely being passed down by formik or redux-form.
`onBlur`	function		A function to call when the input is blurred. Likely being passed down by formik or redux-form.
`isEmptyAndOptional`	boolean	`false`	When `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.

Radio Group

Edit this page