Skip to main content

Pivotal UI

v19.1.2
Components / Autocomplete

Autocomplete

Autocomplete provides the user the ability to search for known entities with the task of retrieval or navigation. For more exploratory search and complex information seeking tasks consider a multi-step workflow or filtering options.

Guidelines

Do'sDon'ts
Use Autocomplete to facilitate accurate and efficient data entryUse Autocomplete when the user needs to explore a dataset
Use Autocomplete to select from a finite list of names, objects or symbols
Basic example

This autocomplete has options for foo, food, and bar.

ReferenceError: React is not defined
Adding more options to autocomplete

By saving the onInitializeItems callback, we can call it whenever we need to give the autocomplete new data. We then use the updateList() method to update the list.

ReferenceError: React is not defined

onInitializeItems

The callback passed to this function should return the values to initially populate the list of items.

It's designed to be able to be used asynchronously:

const onInitializeItems = callback => {
  $.get('example.com/autocomplete_items').then(items => callback(items));
};

But it can also just be used synchronously:

const onInitializeItems = callback => callback(['foo', 'food', 'bar']);

onPick

By default, when a user selects a list item, nothing happens except hiding the list.

const onPick = value => {
  $.post('example.com/add_to_cart?thing=' + value);
};

onSearch

To override the default search algorithm, pass your custom function to the Autocomplete as the prop onSearch.

onSearch is given the current value of the input and a callback.

The callback should return the items that should be shown in the list given that input value.

The list should be an array of objects with the value key e.g. [{value: 'foo'}, {value: 'food'}, {value: 'foe'}]

It's designed to be able to be used asynchronously:

const onSearch = (value, callback) => {
  $.get('example.com/autocomplete_results?value=' + value).then(results => callback(results));
};

But it can also just be used synchronously:

const onSearch = (value, callback) => {
  callback(myCustomList.filter(entry => entry.includes('foo-' + value + '-bar'));
};

Props

PropertyRequiredTypeDefaultDescription
classNamenoStringclassName to add to autocomplete
disablednoBooleanwhether the input is disabled
inputnoObjectautocompleteinputoverrides the input for autocomplete
maxItemsnoNumber50the maximum number of items in the autocomplete list
onClicknoFunctiononClick to add to the input
onFilternoFunctionlets you apply an additional filter to the autocomplete list
onFocusnoFunctiononFocus to add to the input
onInitializeItemsnoFunctiondone => done([])returns the values to initially populate the autocomplete list
onPicknoFunctioncallback when something is picked from the list
onSearchnoFunctionTo override the default search algorithm, pass your custom function to the autocomplete as the prop onSearch.
placeholdernoString'search'placeholder text for the input
showNoSearchResultsnoBooleanfalseIf true, will display 'No search results' when no results are matched. Valid only if no list child is passed. Eg. If you want to provide a custom search results list component, this flag will be ignored.
trieOptionsnoObjectOptions for the default TrieSearch algorithm (e.g. ignoreCase: a boolean is set to true by default, splitOnRegEx: a RegEx)
valuenoStringused when the input is a controlled input

Imports

Import React components (including CSS):

import {Autocomplete, AutocompleteInput} from 'pivotal-ui/react/autocomplete';

Import CSS only:

import 'pivotal-ui/css/autocomplete';