Learn how to build a full autocomplete UI from the ground up.
autocomplete-js output, for example in React or another front-end framework, the
autocomplete-core package provides all the primitives to build it.
This guide shows how to leverage all the autocomplete capacities to build an accessible autocomplete, both for desktop and mobile, with React. You can find the final result in this sandbox.
You might not need a custom renderer
Begin by importing
createAutocomplete from the core package and
getAlgoliaHits from the Algolia preset. The preset—
autocomplete-preset-algolia—is a utility function to retrieve items from an Algolia index.
The Autocomplete entry point is the
createAutocomplete function, which returns the methods to create the autocomplete experience.
Note the following commented portions:
- (1) You can leverage a React state for the autocomplete component to re-render when the Autocomplete state changes.
- (2) You can listen to all Autocomplete state changes to synchronize them with the React state.
- (3) This example uses an Algolia index as a source.
This setup gives you access to all the methods you may want to use in the
autocomplete variable in your React components. Next, you can start building the UI.
Prop getters are methods that return props to use in your components. These props contain accessibility features, event handlers, etc. You don't have to know exactly what they're doing. Their responsibility is to create a complete experience without exposing the underlying technical elements.
This following snippet shows how you can use the
getItemProps() prop getters in the appropriate elements.
The above code demonstrates that you don't need to worry about keyboard events, or tracking which item is active. Autocomplete handles this under the hood with its prop getters.
At this point, you should already have a usable autocomplete input:
To improve the
input control, you can wrap it in a
form and apply the form props given by Autocomplete:
getFormProps prop getter handles submit and reset events. It also respectively blurs and focuses the input when these events happen. You need to pass the
inputElement when calling
getFormProps to leverage this functionality.
You can also add a label that represents the input and use the
getLabelProps prop getter:
Another good practice for search inputs is to display a reset button. You can conditionally display it based on if there's a query.
Displaying UI hints when the network is unstable helps users understand why results are not updating in real time. You can rely on the
status to determine this:
You could, for example, create a
.aa-Panel--stalled CSS class that lowers items' opacity. This convention hints that search is currently stuck or unavailable.
You can learn more about other state properties in the state documentation.
Native platforms offer better primitives for mobile search experiences. Autocomplete aims at providing these capabilities so that the web mobile experience is closer to the the native mobile experience.
A common feature in mobile native experiences is to close the virtual keyboard when the user starts scrolling. This makes the results more discoverable without the user having to manually close the keyboard.
getEnvironmentProps method returns event handlers that let you create this experience:
This way, users feel a bit closer to what they're used to on mobile apps.
You now have enough knowledge to build your own experience based on Autocomplete. If you find that some topics weren't covered, feel free to open an issue.