Autocomplete menu

The Algolia extension for Adobe Commerce and Magento Open Source uses autocomplete.js to create the menu that appears below the search bar. The extension handles:

• Setting up the basic configuration options
• Setting up the sources
• Providing templates to render matching results from the sources

You can find all templates, JavaScript files and style sheets in the directory: vendor/algolia/algoliasearch-magento-2/view/frontend/web

This guide includes references a custom extension template you can download and use as a starting point.

Basic configuration options

You can change these options for your autocomplete menu:

Use the beforeAutocompleteOptions hook to change the autocomplete options. For example:

1
2
3
4
5
algolia.registerHook('beforeAutocompleteOptions', function(options)  {
  // Add or modify options, then return them
  options.debug = true;
  return options;
});

Sources

The autocomplete menu shows matching results from different sources. Each source has options to define which index to query, and the templates for rendering the matching results.

To change the sources, go to Stores > Configuration > Algolia Search > Autocomplete in the Magento admin dashboard. You can select these sources:

If you want to change an existing source or add a new source to the autocomplete menu, you need to use the beforeAutocompleteSources hook. The callback function for beforeAutocompleteSources must return the modified sources array, including the already configured sources.

For example:

1
2
3
4
algolia.registerHook('beforeAutocompleteSources', function(sources, algoliaClient, algoliaBundle)  {
    // Add or modify sources, then return them
    return sources;
});

Click events

When a user selects a search result, the autocomplete menu sends a click event to Algolia:

• If you enabled Click and conversion analytics
• If you configured Personalization

If you want to track custom events, see Custom frontend events.

Keyboard navigation

This feature is available in the Algolia extension for Magento Open Source and Adobe Commerce version 3.9.2 or later.

To change the setting for keyboard navigation, go to Stores > Configuration > Algolia Search > Enable Keyboard Navigation in the Magento dashboard. By default, keyboard navigation is turned on.

Keyboard navigation only works with the up/down keys, the left/right keys have no effect. Autocomplete implements the WAI-ARIA 1.2 combobox specification, which only specifies navigation behavior for the up and down keys.

Autocomplete menu templates

When you update templates, it’s best to keep the changes in your theme directory. Don’t edit the theme files in the extension directory if possible. Follow Adobe Commerce theme development best practices.

To change the appearance of the autocomplete menu, you can override these templates in your theme:

You can find all the js files in the autocomplete directory.

JavaScript mixins with RequireJS

Mixins let you change the rendering of specific parts of a template without having to override the entire file.

To do this, create a requirejs-config.js file in your theme or custom module:

1
2
3
4
5
6
7
8
9
var config = {
    config: {
      mixins: {
        'Algolia_AlgoliaSearch/internals/template/autocomplete/products': {
          'Algolia_CustomAlgolia/template/autocomplete/products-mixin': true
        }
      }
    }
};

A sample products-mixin.js might look as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
// SAMPLE PRODUCT MIXIN
define(function () {
  "use strict";

  const mixin = {
    getItemHtml: function ({ item, components, html }) {
      return html`<a
        class="algoliasearch-autocomplete-hit"
        href="${item.__autocomplete_queryID != null
          ? item.urlForInsights
          : item.url}"
      >
        <div class="thumb">
          <img src="${item.thumbnail_url || ""}" alt="${item.name || ""}" />
        </div>
        <div class="info">
          ${components.Highlight({ hit: item, attribute: "name" })}

          <!-- BEGIN SAMPLE CUSTOMIZATION -->
          <!-- (Adding SKU to autocomplete HTML output) -->
          <div class="sku">${item.sku}</div>
          <!-- END SAMPLE CUSTOMIZATION -->

          <div class="algoliasearch-autocomplete-category">
            ${this.getColorHtml(item, components, html)}
            ${this.getCategoriesHtml(item, components, html)}
          </div>

          ${this.getPricingHtml(item, html)}
        </div>
      </a>`;
    },
  };

  return function (target) {
    return { ...target, ...mixin };
  };
});

In the above example, a mixin was written only for the getItemHtml method in the Autocomplete product hit template to add an item’s sku field to the generated output. All other behavior remains the same.

If you only want to modify specific renderings, you can implement a mixin for methods like getColorHtml or getCategoriesHtml without editing the getItemHtml method.

Mixins allow you to change the rendering of specific pieces of content within a template without having to override the entire file.

Using wrappers

Another approach to building Autocomplete template mixins is via Magento’s supplied mage/utils/wrapper JavaScript module.

The following example overrides the getHeaderHtml method of the Autocomplete category hit template:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// SAMPLE CATEGORIES MIXIN
define(["mage/utils/wrapper"], function (wrapper) {
    "use strict";

    return function (template) {
        template.getHeaderHtml = wrapper.wrapSuper(
            template.getHeaderHtml,
            function (args) {
                const orig = this._super(args);
                return `${orig}: This category template was customized!`;
            }
        );
        return template;
    };
});

One benefit to this approach is that you can invoke the original template function and include its output in the override by calling the wrapper’s _super method.

The result of the previous code is demonstrated below:

To see even more ways to use JavaScript mixins with Magento, reference the Adobe Commerce documentation.

Custom Algolia module

To help you build your mixins faster, try our Algolia_CustomAlgolia extension which will install a set of starter templates that you can customize further for your application.

For more information see Create a custom extension.

Autocomplete menu styles

If you want to change the style of the autocomplete menu, it’s best to enable the debug mode for autocomplete. This keeps the autocomplete menu open and lets you inspect the DOM elements in the autocomplete.

You can enable the debug mode in Stores > Configuration > Algolia Search > Autocomplete > Enable autocomplete menu’s debug mode.

Custom theme

By default, the extension overrides the topSearch block of the template. If you’re using a custom theme without the topSearch block, you need to update the DOM selector for the search input.

Go to Stores > Algolia Search > Autocomplete Menu in the Magento Admin panel, and change the Search Input Container Selector:

If the container selector is defined, the extension overrides the topSearch block and loads the necessary scripts. To give the Autocomplete search-as-you-type menu the look and feel you want, you need to update the styles.