[TECHNICAL] JavaScript events exposed by the 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
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);
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 }));