Autocomplete menu

The Algolia extension for Adobe Commerce and Magento Open Source uses the Autocomplete UI library to create the menu that appears below the search box. You can find all templates, JavaScript files and style sheets in the directory: vendor/algolia/algoliasearch-magento-2/view/frontend/web.

As a starting point for your customizations, you can download a template.

Concepts

Frontend events let you run functions (hooks) at specific stages in the lifecycle of the autocomplete menu. You can use them to change the structure of your data, its sources, and the configuration options for your autocomplete menu. For more information, see Frontend custom events.

Templates let you control the look of your autocomplete menu with JavaScript template literals.

Basic configuration options

To change the autocomplete options, use the afterAutocompleteOptions hook. For example:

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

Sources

Sources provide the data for items that your users can search for in the autocomplete menu. Specifying multiple sources lets you create a federated search experience.

The Algolia extension comes with default sources. To change them, go to Stores > Configuration > Algolia Search > Autocomplete in your Magento Admin. You can select these sources:

Add new sources

To add new sources to the autocomplete menu or change existing ones, use the afterAutocompleteSources hook.

The callback function for afterAutocompleteSources must return the complete sources array.

For example:

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

The callback for afterAutocompleteSources accepts two parameters:

If you need access to other objects, such as algoliaAnalytics, use RequireJS to define them as dependency for your algoliaHooks implementation.

Sources data structure

A minimal configuration for your source object might look like the following:

1
2
3
4
5
6
7
8
9
{
  sourceId: 'my-custom-source',
  indexName: 'my_custom_index',
  templates: {
    item({item, html}) {
      return html`<a href="${item.url}">${item.title}</a>`;
    }
  }
}

Each source in the sources array is a JavaScript object with the following properties:

Examples

The following example hook adds a new source:

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
algolia.registerHook(
    "afterAutocompleteSources",
    function (sources, searchClient) {
        // Add new source to the sources array
        sources.push({
            sourceId : "my-custom-source",
            // Use `algoliaConfig.indexName` to get the index prefix by store scope
            indexName: algoliaConfig.indexName + '_my_custom_index',
            // Add search parameter
            options  : {hitsPerPage: 3},
            templates: {
                // Template for the menu when no results are found
                noResults() {
                    return "No results found";
                },
                // Template for a custom header displayed before all items of this source
                header() {
                    return 'Custom source example';
                },
                // Template for each autocomplete item
                item({item, html}) {
                    return html`<a class="aa-ItemLink" href="${item.url}">${item.title}</a>`;
                }
            }
        });

        // Return the complete sources array
        return sources;
    }
);

The following example changes an existing source:

1
2
3
4
5
6
7
8
9
10
11
algolia.registerHook(
  "afterAutocompleteSources",
  function (sources, searchClient) {
    // Modify the "pages" source
    const pages = sources.find(source => source.sourceId === 'pages');
    pages.transformResponse = ({ hits }) => {
      // Do something with the hits returned by this source
      return hits;
    };
    return sources;
}

Plugins

Plugins extend Autocomplete—for example, by adding new sources. The Magento extension includes the Query Suggestions plugin. This plugin shows popular searches in your autocomplete menu as search suggestions.

To add new plugins or change existing ones, use the afterAutocompletePlugins hook.

For example, to add recent searches to your autocomplete menu:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
algolia.registerHook('afterAutocompletePlugins', (plugins, searchClient) => {
  const recentSearchesPlugin = algoliaRecentSearches.createLocalStorageRecentSearchesPlugin({
      key: 'navbar',
      transformSource({source}) {
          return {
              ...source,
              templates: {
                  ...source.templates,
                  header: () => 'Recent searches',
                  item: ({item, html}) => {
                      return html`<a class="aa-ItemLink" href="${algoliaConfig.resultPageUrl}?q=${encodeURIComponent(item.label)}">${item.label}</a>`;
                  }
              }
          }
      }
  });

  plugins.push(recentSearchesPlugin);

  return plugins;
}

Click events

When a user selects an item in the menu, Autocomplete sends a click event. To track custom events, see Custom frontend events.

Keyboard navigation

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

To turn off keyboard navigation, go to Stores > Configuration > Algolia Search > Enable keyboard navigation in the Magento Admin. By default, keyboard navigation is turned on.

Autocomplete implements the WAI-ARIA combobox pattern.

Autocomplete menu templates

When updating templates, keep the changes in your theme directory. Avoid editing the theme files in the extension directory. Follow theme development best practices.

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

You can find all template files in the web/js/template/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/js/template/autocomplete/products': {
          'Algolia_CustomAlgolia/js/template/autocomplete/products-mixin': true
        }
      }
    }
};

The following mixin example adds the product’s SKU to each product in the autocomplete menu. It overrides the getItemHtml function, leaving other aspects unchanged.

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
// products-mixin.js
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 };
  };
});

To only change specific aspects, you can create mixins for methods such as getColorHtml or getCategoriesHtml without editing the getItemHtml function.

Customization with wrappers

You can also extend templates with Magento’s mage/utils/wrapper JavaScript module. Wrappers let you invoke the original template function and include its output with the _super method.

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;
    };
});

This renders the following results:

For more information, see JavaScript mixins in the Adobe Commerce documentation.

Custom Algolia module

To help you build your mixins faster, try the Algolia_CustomAlgolia extension which installs a set of starter templates for your customizations.

For more information see Create a custom extension.

Styling

To keep the autocomplete menu open when making changes, turn on the debug mode. To enable the debug mode, go to Stores > Configuration > Algolia Search > Autocomplete > Enable autocomplete menu’s debug mode.

Debouncing

Debouncing delays sending a search request until after a brief pause after the last keystroke. This removes instant feedback for users, but also leads to fewer API requests and UI changes. This might help users who prefer reduced motion.

To adjust the debounce settings, go to Stores > Configuration > Algolia Search > Autocomplete in the Magento Admin.

Debounce requests

The Debounce requests setting defines the delay after the last keystroke before triggering a search. By default, a search is triggered 300 milliseconds after the last keystroke.

Minimum query length

The Minimum query length setting defines how many characters users have to enter before triggering a search. If you set it to 0, searches are triggered from the first keystroke.

Custom theme

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

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

Console error after reindexing

If you see the “Cannot read property ‘autocomplete’ of undefined” error after reindexing, this indicates the extension’s templates weren’t rendered.

1. Since the templates are rendered into the before_body_end block, ensure the theme renders this block.
2. If the block is rendered, confirm that symlinks are enabled in Magento’s configuration. Enable this in the administration section by going to System > Configuration > Advanced > Developer.