> For the complete documentation index, see [llms.txt](https://docs.globo.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.globo.io/javascript-events/storefront-javascript-events.md).

# Storefront JavaScript events

The storefront widget dispatches JavaScript events you can listen for in your theme's own code, to trigger custom behavior when a shopper filters, searches, or adds a product to cart.

## What this does

Dispatches JavaScript events on the storefront whenever a shopper filters, searches, or adds a product to cart, so your theme's own code can react to those moments. For example, you could fire a custom analytics tag when `globoFilterSearchCompleted` fires, or trigger a custom animation when `cart:added` fires after a shopper adds a product from the app's own product card/quick-add. The events themselves don't change any storefront behavior — they just notify your code that something happened, and hand it the relevant data (`event.detail`) to work with.

## Prerequisites

* Comfortable adding custom JavaScript to your theme (for example, via a custom section or the theme's JS assets). This page is intended for developers/theme customizers, not store admins.

## How to listen for an event

Add a listener anywhere in your theme's JavaScript, for example right before `</body>`:

```html
<script>
  window.addEventListener('globoFilterRenderCompleted', function (event) {
    console.log('Filter results updated', event.detail);
  });
</script>
```

Events documented with a `document` target instead of `window` are listened for on `document` instead:

```html
<script>
  document.addEventListener('cart:added', function (event) {
    console.log('Product added to cart', event.detail);
  });
</script>
```

## Filter events

| Event                                 | Fires on | When                                                                             | `event.detail`                                                                |
| ------------------------------------- | -------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `globoFilterRenderCompleted`          | `window` | After the product grid finishes re-rendering following a filter change           | `{ products }` — the newly rendered product list (omitted if nothing changed) |
| `globoFilterTreeRenderCompleted`      | `window` | Right after the above, once the filter sidebar/tree itself has finished updating | none                                                                          |
| `globoFilterQuickviewRenderCompleted` | `window` | After a product's "quick view" modal content has been inserted into the page     | none                                                                          |

## Search events

| Event                              | Fires on | When                                                                     | `event.detail`                                                                                               |
| ---------------------------------- | -------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
| `globoFilterSearch`                | `window` | As soon as a search request starts (before results come back)            | the search term (string)                                                                                     |
| `globoFilterSearchCompleted`       | `window` | After search results are fetched and rendered                            | the search result payload (products, suggestions, pages, articles, whether it was empty, and similar fields) |
| `globoFilterRenderSearchCompleted` | `window` | After the search drawer's result markup has been updated for a new query | none                                                                                                         |
| `globoFilterSearchDrawerOpened`    | `window` | After the search drawer/popup has opened and is focused                  | none                                                                                                         |
| `globoFilterCloseSearchCompleted`  | `window` | After the search drawer/popup has finished closing                       | none                                                                                                         |

## Cart event

| Event        | Fires on   | When                                                                                           | `event.detail`                                                                                    |
| ------------ | ---------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `cart:added` | `document` | After a shopper successfully adds a product to cart using the app's own product card/quick-add | `{ product, quantity, properties }` — `product` is Shopify's own cart response for the added item |

## Notes

* These events reflect the app's current behavior; treat them as a convenience for common customizations rather than a guaranteed, versioned API.
* If you need help wiring up a specific integration, contact us at <contact@globo.io>.

## Related pages

* [Get filtered products](/api-reference/get-filter-products.md)
* [Search products](/api-reference/search-products.md)
* [Enable instant search widget](/search/enable-instant-search-widget.md)