Javascript Events for Developers
The Freedom theme emits JavaScript events analogous to Shopify's Dawn theme for developer convenience.
Whenever a major action occurs (like updating the cart or changing a variant), the theme dispatches a standard browser
event to the window object. This allows you to hook into these events using standard JavaScript, making it easy to
integrate third-party apps or custom analytics without modifying the theme's core code.
How to Listen for Events
You can use the standard window.addEventListener method.
Important: The event data is assigned directly to the event object properties, rather than inside a detail object.
window.addEventListener('cart:update', function(event) {
// Access data directly from the event object
const cart = event.cartData;
console.log('New Total Price:', cart.total_price);
});
Cart Events
cart:update
Fires whenever the cart state changes (item added, removed, quantity changed, or discount applied).
Event Data:
- source (String): The origin of the action (e.g., product-form, cart-discount, cart-drawer).
- cartData (Object): The JSON response from Shopify's Cart API containing items, total price, etc.
- variantId (Number): The ID of the specific variant that was updated (optional).
Example:
window.addEventListener("cart:update", (event) => {
console.log("Cart updated via:", event.source);
console.log("Items count:", event.cartData.item_count);
});
cart:error
Fires when a cart action fails (e.g., attempting to add more quantity than is in stock).
Event Data:
- source (String): Origin (e.g., product-form).
- errors (String/Object): Description of the error.
- message (String): The error message returned by Shopify.
Example:
window.addEventListener("cart:error", (event) => {
alert("Could not add to cart: " + event.message);
});
quantity:update
Fires immediately when a quantity input is changed in the UI, before the server request completes.
This event does not emit any data.
window.addEventListener("quantity:update", () => {
console.log("Quantity input changed. UI update pending...");
});
Product Events
variant:change
Fires when a user selects a variant combination that resolves to a valid variant. This is the primary event for updating
prices, SKUs, or availability statuses.
Event Data:
- data.variant (Object): The full JSON object of the selected variant.
- data.sectionId (String): The ID of the section where the change occurred.
Example:
window.addEventListener("variant:change", (event) => {
const variant = event.data.variant;
if (variant) {
console.log("User selected variant ID:", variant.id);
console.log("Variant price:", variant.price);
}
});
option-value-selection:change
Fires immediately when a user clicks an option (swatch, pill, or dropdown), even if a valid variant hasn't been fully
resolved yet.
Event Data:
- data.event (Event): The original DOM click/change event.
- data.target (Element): The input element triggered.
- data.selectedOptionValues (Array): Array of currently selected values.
Example
window.addEventListener("option-value-selection:change", (event) => {
console.log("Option clicked:", event.data.target.value);
console.log("Current selection:", event.data.selectedOptionValues);
});
Reference: Event Names
For convenience, you can refer to this map of event strings.
const THEME_EVENTS = {
cartUpdate: 'cart:update',
quantityUpdate: 'quantity:update',
optionValueSelectionChange: 'option-value-selection:change',
variantChange: 'variant:change',
cartError: 'cart:error',
}