Getting Started
Get started with Autocomplete by building an Algolia search experience.
This documentation offers a few ways to learn about the Autocomplete library:
- Read the Core Concepts to learn more about underlying principles, like Sources and State.
- Follow the Guides to understand how to build common UX patterns.
- Refer to API reference for a comprehensive list of parameters and options.
- Try out the Playground where you can fork a basic implementation and play around.
Keep reading to see how to install Autocomplete and build a basic implementation with Algolia.
#
InstallationThe recommended way to get started is with the autocomplete-js
package. It includes everything you need to render a JavaScript autocomplete experience.
Otherwise, you can install the autocomplete-core
package if you want to build a renderer from scratch.
All Autocomplete packages are available on the npm registry.
If you don't use a package manager, you can use the HTML script
element:
We recommend using jsDelivr but autocomplete-js
is also available through unpkg.
#
Installing the Autocomplete Classic ThemeThe Autocomplete library provides the autocomplete-theme-classic
package so that you can have sleek styling out of the box.
If you want a custom theme, you can use this classic theme and customize it with CSS variables. You can also create a new theme entirely using the classic theme as a starting point.
This example uses the out of the box classic theme. You can import it like any other Autocomplete package.
Then import it in your project:
If you don't use a package manager, you can link the stylesheet in your HTML:
note
We don't provide support regarding third party services like jsDeliver or other CDNs.
#
Defining where to put your autocompleteTo get started, you need a container for your autocomplete to go in. If you don't have one already, you can insert one into your markup:
Then, insert your autocomplete into it by calling the autocomplete
function and providing the container
. It can be a CSS selector or an Element.
Make sure to provide a container (e.g., a div
), not an input
. Autocomplete generates a fully accessible search box for you.
You may have noticed two new options: placeholder
and getSources
. The placeholder
option defines the placeholder text to show until the user starts typing in the input.
Autocomplete is now plugged in. But you won't see anything appear until you define your sources.
#
Defining what items to displaySources define where to retrieve the items to display in your autocomplete dropdown. You define your sources in the getSources
function by returning an array of source objects.
Each source object needs to include a sourceId
and a getItems
function that returns the items to display. Sources can be static or dynamic.
This example uses an Algolia index of e-commerce products as a source. The autocomplete-js
package provides a built-in getAlgoliaHits
function for just this purpose.
The getAlgoliaHits
function requires an Algolia search client initialized with an Algolia application ID and API key. It lets you search into your Algolia index using an array of queries
, which defines one or more queries to send to the index.
This example makes just one query to the "autocomplete" index using the query
from getSources
. For now, it passes one additional parameter, hitsPerPage
to define how many items to display, but you could pass any other Algolia query parameters.
Although you've now declared what items to display using getSources
, you still won't see anything until you've defined how to display the items you've retrieved.
#
Defining how to display itemsSources also define how to display items in your Autocomplete using templates
. Templates can return a string or anything that's a valid Virtual DOM element. The example creates a Preact component called ProductItem
to use as the template for each item.
The given classNames
correspond to the classic theme imported earlier.
The ProductItem
component uses the Snippet
component to only display part of the item's name and description, if they go beyond a certain length. Each attribute's allowed length and the characters to show when truncated are defined in the attributesToSnippet
and snippetEllipsisText
Algolia query parameters in params
.
This is what the truncated JSON record looks like:
Check out how the template displays items by searching in the input below:
#
Going furtherThis is all you need for a basic implementation. To go further, you can use the getItemUrl
to add keyboard accessibility features. It lets users open items directly from the autocomplete menu.
Now give it a try: navigate to one of the items using your keyboard and hit Enter. This brings you to the product detail page on bestbuy.com.
This outlines a basic autocomplete implementation. There's a lot more you can do like:
- define templates for headers, footers, or when there's no results
- add multiple sources, including suggested searches and recent searches
- send Algolia Insights events when a user clicks on an item or adds it to their cart
To learn about customization options, read the Core Concepts or follow one of the Guides.