Quickstart: Implementing Autocomplete with Autocomplete.js

Introduction

This guide provides the fastest way to add a powerful, feature-rich autocomplete widget to your website using the Autocomplete.js library. This JavaScript widget is the recommended integration path for most web-based implementations as it handles all the underlying API calls, renders professional layouts, and automatically tracks analytics for you.

By the end of this guide, you will have a working Luigi's Box Autocomplete widget connected to your search input field.

What you'll learn

How to include the necessary Autocomplete.js script and CSS files in your HTML.
How to write the minimal JavaScript configuration to initialize the widget.
How to link the widget to your search input field.
How to verify that your autocomplete implementation is working.

Who is this guide for

Developers who are looking for a fast, out-of-the-box solution for implementing Luigi's Box Autocomplete on their website.

Prerequisites

Before you start, please ensure you have the following in place:

An HTML search input field on your webpage.
Your Luigi's Box trackerId.

Step-by-step

The integration involves adding some tags to your HTML <head>, ensuring you have an <input> element for your search box, and then adding the initialization script.

Step 1: Add required tags to you HTML `<head>`

For the best performance and styling, add the following lines inside the <head> tag of your webpage. The dns-prefetch link helps the browser connect to Luigi's Box servers faster, and the stylesheet link provides the default styling for the widget.

html

<head>
  <link rel="dns-prefetch" href="//live.luigisbox.com" />
  <link rel="stylesheet" href="https://cdn.luigisbox.com/autocomplete.css" />
</head>

Step 2: Prepare your search input field

Ensure you have an HTML <input> element for your search box. Give it a unique ID so you can easily target it with the script.

html

<form>
  <input id="autocomplete-input" placeholder="Search for...">
  <!-- Other form elements like a search button can go here -->
</form>

Step 3: Add and initialize the Autocomplete.js script

Place the following script block near the end of your HTML <body>, right after your search input field. This script will load the Autocomplete.js library asynchronously and then call an initialization function once it's ready.

html

<script>
  function LBInitAutocomplete() {
    // This function initializes the Luigi's Box Autocomplete widget.
    AutoComplete(
      {
        // --- Configuration Start ---

        Layout: "heromobile",           // Specifies the visual layout. "line", "hero", "grid", and "heromobile" are options.
        TrackerId: "YOUR_TRACKER_ID", // Replace with your actual Tracker ID.
        Locale: "en",             // Set the language for localization (e.g., "en", "de", "sk").
        Types: [                  // Define what content types to search for.
          {
            type: "product",         // Suggest products/items.
            name: "Products"      // The header text for the "item" section.
          },
          {
            type: "category",     // Suggest categories.
            name: "Categories"
          }
        ]

        // --- Configuration End ---
      },
      "#autocomplete-input"       // The CSS selector for your search input field.
    );
  }
</script>
<script
  src="https://cdn.luigisbox.com/autocomplete.js"
  async
  onload="LBInitAutocomplete()"
>
</script>

Key configuration fields explained

Layout: Defines the visual appearance. We've used "line", but "hero", "heromobile", and "grid" are other powerful options.
TrackerId: Your unique identifier for your site within Luigi's Box.
Types: An array specifying which type of content to search for. You can configure each type with its own settings.

Step 4: Add "Top items" suggestions on focus

To provide suggestions the moment a user clicks into an empty search box, you can enhance your configuration. This is a great way to improve product discovery.

You need to add two key options to your AutoComplete configuration:

CloseWhenQueryIsEmpty: false: This top-level option tells the widget to stay open when the input field is empty, which is necessary to display the recommendations.
recommend: {}: Add this object to each content type within your Types array for which you want to show suggestions on focus.

Example: configuration with "Top items"

Here is how you would modify the configuration from Step 3 to enable this feature.

html

<script>
  function LBInitAutocomplete() {
    AutoComplete(
      {
        Layout: "line",
        TrackerId: "YOUR_TRACKER_ID",
        Locale: "en",

        // --- ADD THIS LINE ---
        // This option keeps the widget open when the input is empty
        CloseWhenQueryIsEmpty: false,

        Types: [
          {
            type: "product",
            name: "Products",
            // --- ADD THIS LINE ---
            // This option enables "Top Items" for this type on focus
            recommend: {} 
          },
          {
            type: "category",
            name: "Categories",
            // --- ADD THIS LINE ---
            // Enable "Top Items" for categories as well
            recommend: {}
          }
        ]
      },
      "#autocomplete-input"
    );
  }
</script>
<script
  src="https://cdn.luigisbox.com/autocomplete.js"
  async
  onload="LBInitAutocomplete()"
>
</script>

Step 5: Verify your integration

After adding the code, reload your webpage. Click into the search box and start typing. You should see the Autocomplete widget appear below the input field, showing suggestions for "Products" and "Categories" as you type.

Step 6(Optional): Add more suggestion types

You can easily enhance your autocomplete by showing more types of suggestions, such as popular search queries.

To add popular query suggestions, you simply need to add a new object with type: "query" to your Types array in the AutoComplete configuration.

Example: Configuration with query suggestions

Here is how you would modify the configuration from Step 3 to also include popular searches.

html

<script>
  function LBInitAutocomplete() {
    AutoComplete(
      {
        Layout: "heromobile",
        TrackerId: "YOUR_TRACKER_ID",
        Locale: "en",
        CloseWhenQueryIsEmpty: false,
        Types: [
          {
            type: "item",
            name: "Products",
            recommend: {} 
          },
          {
            type: "category",
            name: "Categories",
            recommend: {}
          },
          // --- ADD THIS OBJECT ---
          {
            type: "query",
            name: "Popular Searches",
            recommend: {} // Also show trending queries on focus
          }
        ]
      },
      "#autocomplete-input"
    );
  }
</script>
<script
  src="https://cdn.luigisbox.com/autocomplete.js"
  async
  onload="LBInitAutocomplete()"
>
</script>

Best Practices

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 for autocomplete impressions or clicks when using this library.
Content security policy (CSP): If your website uses a strict CSP, you will need to add rules to allow scripts and styles from https://cdn.luigisbox.com and connections to https://live.luigisbox.com.
Potential conflicts: Some third-party scripts (like older versions of Mootools or certain cookie consent managers) can interfere with script loading. If the widget doesn't initialize, consult the Autocomplete js documentation for workarounds, such as using different event listeners for initialization.

Next Steps

Now that you have a basic Autocomplete widget running, you can explore its more advanced features:

Customize the widget: Learn how to change layouts, add "Add to Cart" buttons, and use advanced formatting options by referring to our "Customizing Autocomplete.js: Layouts, actions, and advanced options" guide.
Integrate directly with the API: If you need more control than the Autocomplete.js widget provides, your next step would be to read the "Quickstart: Getting query suggestions via the Autocomplete API" guide.