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, use the CustomAlgolia starter code.

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

Autocomplete option	Description
`placeholder`	Text shown in the search box before users type
`debug`	If true, the Autocomplete menu stays open even if you click outside it
`openOnFocus`	If true, the Autocomplete menu displays as soon as a user clicks on the search input field

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

JavaScript

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:

Autocomplete source	Description
`products`	Products from your catalog
`categories`	Product categories
`pages`	Pages
`suggestions`	Suggestions from popular searches
`additional_sections`	Additional sections you configured in the Magento Admin

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:

JavaScript

algolia.registerHook(
  "afterAutocompleteSources",
  function (sources, algoliaClient) {
    // Add or modify sources, then return them
    return sources;
  },
);

The callback for afterAutocompleteSources accepts two parameters:

Parameter	Type	Description
`sources`	Array of sources	Data for autocomplete items
`searchClient`	Search client	Initialized Algolia search client

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:

JavaScript

{
  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:

Property	Type	Required	Description
`sourceID`	String	Required	Unique identifier for your source. Use a `sourceID` of a built-in source to override it.
`indexName`	String	Required	Index name. It’s records will be searchable in the autocomplete menu. To reference a Magento store index, use `algoliaConfig.indexName` as prefix.
`templates`	Autocomplete templates	`item` template is required	Templates for rendering items (`item`), no-results display (`noResults`), a header (`header`), and footer (`footer`).
`getItemUrl`	function		Function to return the URL for an item for keyboard navigation.
`transformResponse`	function		Function to transform the response from the Algolia API before turning it to Autocomplete items. For more information, see `getAlgoliaResults`.
`options`	Search parameters	Add or override Algolia search parameters, such as the `hitsPerPage` parameter.

Examples

The following example hook adds a new source:

JavaScript

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:

JavaScript

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:

JavaScript

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 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.

Screenshot of two drop-down menu: 'Enable autocomplete menu's debug mode' and 'Enable keyboard navigation', both set to 'Yes'.

Autocomplete implements the WAI-ARIA combobox pattern.

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:

Template file	Description
`autocomplete.phtml`	Autocomplete menu
`products.js`	Products
`categories.js`	Categories
`pages.js`	Pages
`suggestions.js`	Search suggestions
`additional-section.js`	Additional sections

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:

JavaScript

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.

JavaScript

// 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:

Javascript

// 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:

Using wrappers in your mixins for invoking the original method and using its output

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 waits to send a until the user stops typing for a short time. This reduces the number of API requests and UI updates but it also delays showing results. Debouncing can help users who prefer reduced motion. To change 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:

Screenshot of settings with 'Enable Autocomplete Menu' set to 'Yes', 'Search Input Container Selector' as '.Algolia-search-input', and 'Number of products' set to '6'.

Console error after reindexing

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

Since the templates are rendered into the before_body_end block, ensure the theme renders this block.
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.

AdobeCommerce/Magento

Autocomplete menu

Concepts

Basic configuration options

Sources

Add new sources

Sources data structure

Examples

Plugins

Click events

Keyboard navigation