Autocomplete extends the standard Combobox component to dynamically fetch its options from an API call as the user types into the field.

Rather than have very long lists embedded in your page, slowing rendering, the autocomplete component can be used instead. By default1, this sends a "GET" request to an endpoint (suggestionsApiSearchUrl), appending the search text to the end of the url. The resulting response is parsed, and presented to the user.

Where necessary, the selected auto-complete option may be queried/set/cleared via the selectedOption property (see the "Implementation" table in the "Code" tab above for further details).

A requirement for the use of the autocomplete component is that the response from the server1 is a JSON array of objects, containing statically named fields which can be mapped to values and labels for the suggestions. The label field in the response is mapped from the apiResponseSuggestionLabelFieldname property, and the value field in the response is mapped from the apiResponseSuggestionValueFieldname property.

There is a timing threshold (inputKeyDebounceMillis), which means that fast typing does not result in large numbers of requests. This defaults to 200ms - a larger value will result in fewer requests, but might start to become a noticable delay to the end user.

1 NB: For more complex use-cases (e.g. where the API being called requires additional request headers, requires that the request be a "POST" rather than a "GET", or perhaps returns a more deeply nested JSON structure that needs to be "flattened" in order to comply with the structure assumed by the component, etc), the default ("GET") behaviour may be overriden by providing a suitable function as the value of (optional, function-valued) property: customFetchResultsFunction. For details on the arguments and supported return types for such functions, please refer to the documentation for this property in the "Implementation" table in the "Code" tab above.

See Combobox

Our components have been designed to comply with the WCAG 2.1 AA accessibility guidelines. For information about how our design system complies with color-related accessibility guidelines, see Foundations > Colors > Accessibility.

Related components: