--- title: "Implementing autocomplete with Autocomplete.js" description: "Learn how to add a feature-rich autocomplete widget to a website using the recommended Autocomplete.js library, which automates API calls and analytics for the fastest integration." slug: quickstart/autocomplete/with-autocompletejs docKind: guide hub: quickstart --- ## Introduction This guide provides the fastest way to add a powerful, feature-rich autocomplete widget to your website using the [Autocomplete.js](/autocomplete/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](/autocomplete/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 ``, ensuring you have an `` element for your search box, and then adding the initialization script. ### Step 1: Add required tags to your HTML `` For the best performance and styling, add the following lines inside the `` 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 ``` ### Step 2: Prepare your search input field Ensure you have an HTML `` element for your search box. Give it a unique ID so you can easily target it with the script. ```html ``` ### Step 3: Add and initialize the Autocomplete.js script Place the following script block near the end of your HTML ``, 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 ``` #### 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" on focus To show Top Items 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: 1. `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. 2. `recommend: {}`: Add this object to each content type within your `Types` array for which you want to show Top Items on focus. #### Example: configuration with "top items" Here is how you would modify the configuration from Step 3 to enable this feature. ```html ``` ### 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 ``` ## 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](/autocomplete/autocomplete-js/#compatibility) documentation for workarounds, such as using different event listeners for initialization. ## Next steps - **Customize the widget:** Learn how to change layouts, add "Add to Cart" buttons, and use advanced formatting options in our [Customizing Autocomplete.js](/quickstart/autocomplete/customizing-autocompletejs/) guide. - **Integrate directly with the API:** If you need more control than the Autocomplete.js widget provides, read the [Getting query suggestions via the Autocomplete API](/quickstart/autocomplete/query-suggestions/) guide.