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.
<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.
<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.
<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 yourTypes
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.
<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.
<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 tohttps://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: