> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.bigcommerce.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server.

# Event Hooks

Plan: Stencil Developer

Lesson 15 of 31 · 15 min

Developers use "hooks" to trigger defined events. A theme can "hook" into an event to perform actions or calculations based on a shopper's behavior.

Stencil themes incorporate event hooks by importing the **stencil-utils module**.  Take a look at *cornerstone/assets/js/theme/*, and you will see the import statement *'import utils from '@bigcommerce/stencil-utils';* at the top of files leveraging event hooks.

## Cookie Notification Example

In the example below, the *cookie-privacy-notification* hook enables customization of the alert window that displays European Union-required cookie notifications.

To get started, first, ensure you have loaded the **stencil-utils** package with the following command:

```jsx showLineNumbers={false}
import utils from '@bigcommerce/stencil-utils';
```

> **Info**
>
> **DID YOU KNOW?** European websites must notify users of cookies to comply with European Union law. The following code implements a hook that will alert shoppers that the website uses cookies.

You can override the default browser alert box. When or why would you do this? See below.

```js showLineNumbers={false}
export default function() {

  // Here you can override the default browser alert box by
  // hooking to the 'cookie-privacy-notification' hook.
  utils.hooks.on('cookie-privacy-notification', (event, privacyMessage) => {

    // You can make your own custom modal or alert box
    // appear in your theme using the privacyMessage provided
    myCustomAlert(privacyMessage);

    // Call event.preventDefault() to prevent the default
    // browser alert from occurring in stencil-utils
    event.preventDefault();
  });
}
```

A theme would listen for the *cookie-privacy-notification* event to override the browser's default notification UI.

## Cart Dialog Example

In the following code snippet from Cornerstone in\_templates/components/products/product-view\.html\_, note the data tag named *data-cart-item-add*:

```jsx showLineNumbers={false}
<form class="form" method="post" action="{{product.cart_url}}"
    enctype="multipart/form-data" data-cart-item-add>
```

This data tag enables the emission of the *cart-item-add* event in this next snippet:

```js showLineNumbers={false}
/*
 * Import all product-specific js
 */
[...]
import utils from '@bigcommerce/stencil-utils';
[...]
addProductToCart() {
    utils.hooks.on('cart-item-add', (event) => {
        event.preventDefault();
    });
}
```

## Stencil Data Tags and Event Hooks

Stencil themes provide the following chains of data tags; delegated DOM (Document Object Model) events, emitted Stencil event hooks and Stencil event parameter(s).

### Cart Item Added

Hook for items added to the customer's shopping cart.

**Function Signature:**

```js showLineNumbers={false}
itemAdd() {
    this.$body.on('submit', '[data-cart-item-add]', (event) => {
        this.emit('cart-item-add', event, event.target);
    });
}
```

| **Data Tag**       | **Delegated DOM Event** | **Stencil Event/Hook** | **Stencil Event Parameters** |
| ------------------ | ----------------------- | ---------------------- | ---------------------------- |
| data-cart-item-add | submit                  | cart-item-add          | event, event.target          |

### Faceted-Search Events

Hooks for faceted-search selections that the customer initiates or submits.

**Function Signature:**

```js showLineNumbers={false}
searchEvents() {
  this.$body.on('click', '[data-faceted-search-facet]', (event) => {
        this.emit('facetedSearch-facet-clicked', event);
  });

  this.$body.on('submit', '[data-faceted-search-range]', (event) => {
        this.emit('facetedSearch-range-submitted', event);
  });
}
```

| **Data Tag**              | **Delegated DOM Event** | **Stencil Event/Hook**        | **Stencil Event Parameters** |
| ------------------------- | ----------------------- | ----------------------------- | ---------------------------- |
| data-faceted-search-facet | click                   | facetedSearch-facet-clicked   | event                        |
| data-faceted-search-range | submit                  | facetedSearch-range-submitted | event                        |

## Resources

* [cookieNotification.js](https://github.com/bigcommerce/cornerstone/blob/637ef1b0ff130333aea128663daa6d1a4d37fb78/assets/js/theme/global/cookieNotification.js)