Skip to content

useAsyncSuggestions

Loads suggestions for typed text after a pause, and reports why one is highlighted.

Type to search, such as “re”.

Installation

  1. Add the registryOnce per project
  2. Add use-async-suggestions

Usage

load runs once the query has stayed the same for delay milliseconds. It receives the trimmed query and a signal that aborts when users type again, so a slow response never replaces a newer one. An empty query loads nothing.

While new suggestions load, items keeps the last ones so the list doesn't flash empty. loading and error report the state of the latest load. deps lists what load reads besides the query, such as a selected category, and suggestions load again when any of them changes.

This is the hook behind loadItems in Autocomplete and loadSuggestions in Tag Input.

In an Autocomplete or Combobox

When you build on Base UI's Autocomplete or Combobox, pass onItemHighlighted to the root's prop of the same name. getHighlight() then reports why the highlighted suggestion is highlighted: users chose it with the keyboard or pointer (chosen), it was highlighted automatically (auto), or it was highlighted automatically among results that are being replaced (stale). Pressing Enter on a stale suggestion should submit the typed text rather than pick the suggestion.

getSeen() returns every suggestion loaded so far for the current deps, such as to accept one that users typed out in full. When you pass itemToStringValue, it returns one suggestion for each text.

API

useAsyncSuggestions

useAsyncSuggestions(query, options?) takes the typed text and these options.

It returns:

The file also exports LoadSuggestions<Item>, the type of load, and SuggestionHighlight, the type getHighlight returns.