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',
}