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.