Skip to main content
To view the available Autocomplete or InstantSearch hooks, go to your BigCommerce store, open your browser’s developer tools console, and enter algoliaAutocompleteConfig.hooks or algoliaInstantsearchConfig.hooks.

​
Use custom hooks

To use these hooks, add a new JavaScript file to your theme using the BigCommerce Script Manager.

​
Create a script file

  1. Go to the BigCommerce Script Manager and click Create a Script.
  2. Complete the script form settings:
    • Name. Enter a name for the script.
    • Description. Enter a description for the script.
    • Placement. Select Header.
    • Location. Select All pages.
    • Script Category. Select Essential.
    • Script type. Select Script.
  3. If you want to add custom JS code for Autocomplete or InstantSearch hooks, add it to the Script Contents field.
For example:
JavaScript
document.addEventListener(
  "algoliaInstantsearchConfig.hooks.initialize",
  function () {
    algoliaInstantsearchConfig.hooks.registerHook(
      "instantSearchResultTemplate",
      function (options) {
        /* */
      },
    );
  },
);

document.addEventListener(
  "algoliaAutocompleteConfig.hooks.initialize",
  function () {
    algoliaAutocompleteConfig.hooks.registerHook(
      "AutocompleteResultTemplate",
      function (options) {
        /* */
      },
    );
  },
);
The return values of the function you register with the hook must match the expected return type, indicated by the hook’s name.
Hook name ends withExpected return type
OptionsObject
Templatetagged template literal
ArrayArray of strings or objects
StringString
NumberNumber
ActionFunction

​
Autocomplete hooks

The following hooks change the behavior of the autocomplete menu:

​
autocompleteInitOptions

Sets parameters for the autocomplete menu. Example:
JavaScript
document.addEventListener(
  "algoliaAutocompleteConfig.hooks.initialize",
  function () {
    algoliaAutocompleteConfig.hooks.registerHook(
      "autocompleteInitOptions",
      function (options) {
        // Change the placeholder text of the autocomplete menu
        options.placeholder = "Search Our Products";
        return options;
      },
    );
  },
);

​
autocompleteResultTemplate

Changes the HTML template that renders the Autocomplete results panel Example:
JavaScript
document.addEventListener(
  "algoliaAutocompleteConfig.hooks.initialize",
  function () {
    algoliaAutocompleteConfig.hooks.registerHook(
      "autocompleteResultTemplate",
      function (originalTemplate, html, item, insights) {
        // Updates the html template of the autocomplete menu
        return html` <a class="aa-GridItem" href="${item.url}">
          <div class="aa-ItemContentBody">
            <div class="aa-ItemPicture">
              <img src="${item.image_url}" alt="${item.name}" />
            </div>
            <div class="aa-ItemContentNameWrapper">
              <div class="aa-ItemContentTitle">
                <span>${item.name}</span>
              </div>
            </div>
            <div class="aa-ItemContentBodyFooter">
              <div class="aa-ItemContentPrice">${item.default_price}</div>
              <a class="add-to-cart"> Add To Cart </a>
            </div>
          </div>
        </a>`;
      },
    );
  },
);

​
InstantSearch hooks

The following hooks change the behavior of the search results page:

​
instantSearchInitOptions

Changes InstantSearch options. Example:
JavaScript
document.addEventListener(
  "algoliaInstantsearchConfig.hooks.initialize",
  function () {
    algoliaInstantsearchConfig.hooks.registerHook(
      "instantSearchInitOptions",
      function (options) {
        // Modify default options, then return them
        options.indexName = "BigCommerce";
        return options;
      },
    );
  },
);

​
instantSearchResultTemplate

Changes the HTML template that renders the Autocomplete results panel Example:
JavaScript
document.addEventListener(
  "algoliaInstantsearchConfig.hooks.initialize",
  function () {
    algoliaInstantsearchConfig.hooks.registerHook(
      "instantSearchResultTemplate",
      function (originalTemplateHtml, html, hit, sendEvent) {
        // Modify html template for InstantSearch results
        return html` <a class="ais-hit-details" href="${hit.url}">
            <div class="ais-hit-image">
              <img src="${hit.image_url}" align="left" alt="${hit.name}" />
            </div>
            <div class="ais-hit-title">${hit.name}</div>
          </a>
          <div class="ais-hit-price">${hit.default_price}</div>
          <a class="aa-ItemActionButton" data-product-id="${hit.objectID}">
            Add to cart
          </a>`;
      },
    );
  },
);

​
Recommend hooks

The following hooks change the options used for initializing Recommend:

​
recommendInitOptions

Changes the Recommend initialization options. For example:
JavaScript
document.addEventListener(
  "algoliaRecommendConfig.hooks.initialize",
  function () {
    algoliaRecommendConfig.hooks.registerHook(
      "recommendInitOptions",
      function (options) {
        // Change the index name
        options.indexName = "NewIndexName";
        return options;
      },
    );
  },
);

​
recommendResultTemplate

Changes the HTML template that renders the Recommend results panel. For example:
JavaScript
document.addEventListener(
  "algoliaRecommendConfig.hooks.initialize",
  function () {
    algoliaRecommendConfig.hooks.registerHook(
      "recommendResultTemplate",
      function (originalTemplate, html, item) {
        // Updates the Recommend menu's HTML template
        return html`
          <a href=${item.url}>
            <div class="auc-Recommend-img">
              <img src=${item.image_url} alt=${item.name} />
            </div>
            <div class="auc-Recommend-title">${item.name}</div>
          </a>
          <div class="auc-Recommend-price">${item.default_price}</div>
          <a class="auc-Recommend-addToCart" data-product-id=${item.objectID}>
            Add to cart
          </a>
        `;
      },
    );
  },
);

​
Add new custom hooks

To add new custom hooks, add them to the allowed list and edit the JavaScript file to add a new event trigger. You can’t add custom hooks for Recommend.

​
Add new hooks to the allowed list

  1. Go to the BigCommerce Script Manager.
  2. Create or edit BigCommerce Algolia hooks script.
  3. Add the new hook to the allowedHooks array.
Autocomplete example:
JavaScript
document.addEventListener(
  "algoliaAutocompleteConfig.hooks.initialize",
  function () {
    algoliaAutocompleteConfig.hooks.allowedHooks.push(
      "autocompleteFiltersArray",
    );

    algoliaAutocompleteConfig.hooks.registerHook(
      "autocompleteFiltersArray",
      function (filter) {
        return filter.push(`is_visible=1`);
      },
    );
  },
);
InstantSearch example:
JavaScript
document.addEventListener(
  "algoliaInstantsearchConfig.hooks.initialize",
  function () {
    algoliaInstantsearchConfig.hooks.allowedHooks.push(
      "instantSearchFiltersArray",
    );

    algoliaInstantsearchConfig.hooks.registerHook(
      "instantSearchFiltersArray",
      function (filter) {
        return filter.push(`is_visible=1`);
      },
    );
  },
);

​
Edit the JavaScript file

  1. Edit your Autocomplete or InstantSearch JavaScript file in Search Settings.
  2. Add a new event trigger to the JavaScript file.
Autocomplete example:
JavaScript
algoliaAutocompleteConfig.hooks.triggerHooks(
  "autocompleteFiltersArray",
  autocompleteFilters,
);
InstantSearch example:
JavaScript
algoliaInstantsearchConfig.hooks.triggerHooks(
  "instantSearchFiltersArray",
  instantsearchFilters,
);
⌘I