Custom hook events

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

Go to the BigCommerce Script Manager and click Create a Script.
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.
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 with	Expected return type
`Options`	Object
`Template`	tagged template literal
`Array`	Array of strings or objects
`String`	String
`Number`	Number
`Action`	Function

Autocomplete hooks

The following hooks change the behavior of the autocomplete menu:

autocompleteInitOptions
autocompleteResultTemplate

`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
instantSearchResultTemplate

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

The following hooks change the options used for initializing Recommend:

recommendInitOptions
recommendResultTemplate

`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

Go to the BigCommerce Script Manager.
Create or edit BigCommerce Algolia hooks script.
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

Edit your Autocomplete or InstantSearch JavaScript file in Search Settings.
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,
);

​Use custom hooks

​Create a script file

​Autocomplete hooks

​autocompleteInitOptions

​autocompleteResultTemplate

​InstantSearch hooks

​instantSearchInitOptions

​instantSearchResultTemplate

​Recommend hooks

​recommendInitOptions

​recommendResultTemplate

​Add new custom hooks

​Add new hooks to the allowed list

​Edit the JavaScript file

Use custom hooks

Create a script file

Autocomplete hooks

`autocompleteInitOptions`

`autocompleteResultTemplate`

InstantSearch hooks

`instantSearchInitOptions`

`instantSearchResultTemplate`

Recommend hooks

`recommendInitOptions`

`recommendResultTemplate`

Add new custom hooks

Add new hooks to the allowed list

Edit the JavaScript file