JavaScript events exposed by the theme
This technical documentation only applies to our theme Impact and Prestige v7 (and higher). 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} |
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 form = event.target; // The form that triggers the change });
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.
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.
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".
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 }));