[TECHNICAL] JavaScript events exposed by the theme

This technical documentation only applies to our theme Impact. While we plan to further extend our other themes to share the same technical foundation, if you are using a different theme, please refer to the file "custom.js" inside the Assets folder to access the technical documentation for your theme.

To allow you to easily extend the theme without modifying the internals or to be notified when something happens in the theme, several events are triggered in JavaScript.

Product events

Variant has changed

This event is fired whenever a user has changed the variant in a product selector, either in a product page, featured product section or quick buy.

name	target	detail
`variant:change`	the form that controls the variant	{variant, previousVariant, product}

Example usage:

document.addEventListener('variant:change', function(event) {
  let variant = event.detail.variant; // Gives you access to the whole variant details
  let previousVariant = event.detail.previousVariant; // Gives you access to the details of the previously selected variant
  let product = event.detail.product; // Gives you access to the whole product that the variant belongs to
  let form = event.target; // The form that triggers the change
});

Product actions

Change the variant programmatically

Sometimes, you may want to manually change the selected variant for a given product. For instance, you may have added a checkbox in your form that, when enabled, would change the selected variant automatically. To do that, you need to retrieve the element in the DOM, and call the selectVariant with the associated ID of the variant. The theme will then make sure to update every selector accordingly:

const variantPicker = document.querySelector('variant-picker');
variantPicker.selectVariant(12345);

A page may contain more than one `variant-picker` element. Make sure to create a selector that is sufficiently precise to get the correct picker.

Cart events

Variant added to cart

This event is fired whenever one or more variants are added to the cart through a form selector (product page, quick view...). This event also includes the cart content after an update. As of today, you will get at max one variant, but you may extend the form to add multiple items in one call.

This event is not triggered when a line item already in the cart has changed. To capture this event, you must listen to the more generic "cart:change" event

name	target	detail
`variant:add`	-	{items, cart}

Example:

document.addEventListener('variant:add', function(event) {
  let items = event.detail.items; // Get items added
  let cart = event.detail.cart; // The whole cart content after the update
});

Cart line item has changed

This event is emitted when a line item quantity is changing. It gives you access to the new quantity and the whole cart content after an update.

This event is not triggered when a variant that was not in the cart is added. To listen to that, use the `variant:add` event instead.

name	target	detail
`line-item:change`	lineItem element	{quantity, cart}

Example:

document.addEventListener('line-item:change', function(event) {
  let finalQuantity = event.detail.quantity; // New quantity (may be 0 !)
  let cart = event.detail.cart;
});

Cart content has changed

This event is fired whenever the cart content has changed (if the quantity of a variant has changed if a variant has been removed...). This event will also be emitted when a new variant has been added (so you will receive both "variant:add" and "cart:change").

It is effectively a more generic event that allows to be notified of both "variant:add" and "line-item:change".

The cart:change event also exposed the "baseEvent" attribute which tells you which event caused the change in the cart. For now, only the following values are supported: "variant:add" or "line-item:change".

This event is not triggered when the cart note only has changed.

name	target	detail
`cart:change`	-	{cart, baseEvent}

Example:

document.addEventListener('cart:change', function(event) {
  let cart = event.detail.cart; // Get the updated content of the cart
  let baseEvent = event.detail.baseEvent; // Get the base event
});

Cart error

Sometimes, adding a product to the cart may fail. This may be the case if you are trying to add more quantity than what you have in stock. While the theme will, out of the box, show visual feedback, you may want to listen to this event to add your logic on top of it.

name	target	detail
`cart:error`	-	{error}

document.addEventListener('cart:error', function(event) {
  let error = event.detail.error; // Get the error message returned by Shopify
});

Refresh the cart content

Some advanced customizations may require force update the UI (such as the cart count, drawer...). You can send a specific event that will instruct the theme to refresh the content. To do that, you need to send the event cart:refresh on the documentElement:

document.documentElement.dispatchEvent(new CustomEvent('cart:refresh', {
  bubbles: true
}));

This will ONLY update the UI. This will not, for instance, automatically open the mini-cart. To do that, you will need to open it manually in JavaScript.