> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom hook events

> Hooks are functions that run at specific points of the Algolia app's lifecycle.
They let you register custom functions that change certain aspects of the Autocomplete and InstantSearch integrations.


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](https://support.bigcommerce.com/s/article/Using-Script-Manager).

### Create a script file

1. Go to the [BigCommerce Script Manager](https://support.bigcommerce.com/s/article/Using-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:

```js JavaScript icon=code theme={"system"}
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals) |
| `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`](#autocompleteinitoptions)
* [`autocompleteResultTemplate`](#autocompleteresulttemplate)

### `autocompleteInitOptions`

Sets [parameters](/doc/ui-libraries/autocomplete/api-reference/autocomplete-js/autocomplete#parameters) for the autocomplete menu.

Example:

```js JavaScript icon=code theme={"system"}
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:

```js JavaScript icon=code theme={"system"}
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`](#instantsearchinitoptions)
* [`instantSearchResultTemplate`](#instantsearchresulttemplate)

### `instantSearchInitOptions`

Changes [InstantSearch options](/doc/api-reference/widgets/instantsearch/js#options).

Example:

```js JavaScript icon=code theme={"system"}
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:

```js JavaScript icon=code theme={"system"}
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`](#recommendinitoptions)
* [`recommendResultTemplate`](#recommendresulttemplate)

### `recommendInitOptions`

Changes the Recommend initialization options.

For example:

```js JavaScript icon=code theme={"system"}
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:

```js JavaScript icon=code theme={"system"}
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](/doc/integration/bigcommerce/search-settings/instantsearch#customize-the-instantsearch-menu).

2. [Create or edit](#create-a-script-file) BigCommerce Algolia hooks script.

3. Add the new hook to the `allowedHooks` array.

Autocomplete example:

```js JavaScript icon=code theme={"system"}
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:

```js JavaScript icon=code theme={"system"}
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**](/doc/integration/bigcommerce/search-settings/instantsearch#customize-the-instantsearch-menu).

2. Add a new event trigger to the JavaScript file.

Autocomplete example:

```js JavaScript icon=code theme={"system"}
algoliaAutocompleteConfig.hooks.triggerHooks(
  "autocompleteFiltersArray",
  autocompleteFilters,
);
```

InstantSearch example:

```js JavaScript icon=code theme={"system"}
algoliaInstantsearchConfig.hooks.triggerHooks(
  "instantSearchFiltersArray",
  instantsearchFilters,
);
```