Quickstart: Customizing Autocomplete.js, layouts, actions, and advanced options
Introduction
This guide is for developers who have already implemented a basic autocomplete widget using our "Quickstart: Implementing Autocomplete with Autocomplete.js". Now that you have a working setup, you can explore the advanced configuration options available in the Autocomplete.js
library to tailor the widget's appearance and functionality to your specific needs.
We will cover customizing layouts, adding interactive actions, filtering results, and more. All options are configured within the main AutoComplete({...})
settings object.
What you'll learn
- How to change the visual layout of the autocomplete widget.
- How to add custom interactive actions, like an "Add to Cart" button, to your suggestions.
- How to pre-filter the suggestions that appear in the widget.
- How to customize text and translations for multi-language sites.
Who is this guide for
- Developers who have implemented the basic Autocomplete.js quickstart and want to explore its advanced customization features.
Prerequisites
Before you start, please ensure you have the following in place:
- A working autocomplete implementation based on the Autocomplete.js quickstart guide.
- Familiarity with the basic AutoComplete configuration object.
Step-by-step
We will now modify the code from the previous guide. The changes involve adding a new API endpoint, creating a function to fetch top items, updating your analytics tracking, and adding a focus
event listener.
Step 1: Change the visual layout
The Autocomplete.js
library comes with several built-in layouts that you can choose from using the Layout option. The three main layouts are line, grid, and heromobile.
Let's change the heromobile
layout from our quickstart to the grid
layout.
Example: Modify AutoComplete configuration
AutoComplete({
// --- CHANGE THIS ---
Layout: "grid", // Change from "heromobile" to "grid"
TrackerId: "YOUR_TRACKER_ID",
Locale: "en",
CloseWhenQueryIsEmpty: false,
Types: [
{ type: "item", name: "Products", recommend: {} },
{ type: "category", name: "Categories", recommend: {} }
]
// ... rest of your configuration
}, "#your-search-input");
By simply changing the Layout value, you can dramatically alter the widget's appearance. Luigi's Box recommends "heromobile"
.
Step 2: Add an "add to cart" action
You can add interactive buttons to your suggestion items using the Actions
configuration option. This is perfect for allowing users to add a product directly to their cart from the autocomplete dropdown.
The Actions
option is an array of action objects. We'll add one that only appears for product (item
) suggestions.
Example: Add the Actions
array to your configuration
AutoComplete({
Layout: "grid",
TrackerId: "YOUR_TRACKER_ID",
Types: [{ type: "item", name: "Products" }],
// --- ADD THIS ENTIRE SECTION ---
Actions: [
{
// Only show this action for rows that are products
forRow: function (row) {
return row.type === "item";
},
iconUrl: "https://www.yourshop.com/assets/buy-icon.png", // Use your own icon URL
title: "Add to Cart",
action: function (event, result) {
// Prevent the default click action (navigating to the product)
event.preventDefault();
// Your custom logic here
const productId = result.url; // Assuming URL is the product ID
console.log(`Adding product ${productId} to cart...`);
// e.g., your_sites_add_to_cart_function(productId);
}
}
]
// ... rest of your configuration
}, "#your-search-input");
The action
function gives you full control over what happens when the button is clicked, allowing you to integrate it with your site's cart logic.
Step 3: Add contextual filtering
You can pre-filter suggestions to make them more relevant to the page the user is on. For example, on a "Women's Apparel" category page, you might want the autocomplete only to suggest products from that specific category. You can achieve this with the defaultFilters
option within a Type
configuration.
Example: Add defaultFilers
to a specific type
AutoComplete({
Layout: "hero",
TrackerId: "YOUR_TRACKER_ID",
Types: [{
type: "item",
name: "Products for Her",
// --- ADD THIS ---
// This filter ensures only items with category: "her" are shown
defaultFilters: {
category: "her"
}
}]
// ... rest of your configuration
}, "#your-search-input");
This makes the autocomplete "smarter" by adapting its suggestions to the user's current browsing context.
Step 4: Customize text (localization)
You can easily change the default text of the widget (e.g., "Show all products", section headers) for different languages using the Locale
and Translations
options.
Example: Add the Translations
object to your configuration
AutoComplete({
Layout: "grid",
TrackerId: "YOUR_TRACKER_ID",
Locale: "en", // The current language of the website
Types: [{ type: "item", name: "Products" }],
// --- ADD THIS ---
Translations: {
en: {
// Override only the translations you want to change
showAllTitle: "View All Matching Results",
types: {
item: {
recommendName: "Our Top Picks" // Changes the title for on-focus items
}
}
}
}
}, "#your-search-input");
This allows you to fully integrate the widget's language with the rest of your site and even create dictionaries for languages not supported by default.
Best Practices
-
Trust automatic analytics: One of the biggest advantages of
Autocomplete.js
is that it handles sending all necessary analytics events automatically. You do not need to implement manual tracking when using this library. -
Set Content Security Policy (CSP): To minimize the response size and improve speed, use the optional
hit_fields
parameter in your API call to request only the attributes you actually need to display (e.g.,&hit_fields=title,price,image_link
). -
Check for conflicts: Some third-party scripts (like older versions of Mootools) can interfere with
Autocomplete.js
. If you encounter issues, the autocomplete reference page offers workarounds.
Next Steps
Now that you have learned how to customize your Autocomplete.js
widget, you can either continue to explore more advanced options or consider a direct API integration if you need even greater control.