Appearance

Theme events ​

theme:variant:change ​

Dispatched when the variant changes.

Event detail ​

  • productRootEl: the product root element
  • formEl: the product form element
  • variant: the new variant object
  • previousVariant: the previous variant object
  • product: the product object (product.variants contains all variants)

Examples ​

JavaScript ​

JavaScript
document.addEventListener('theme:variant:change', (e) => {
  const {
    productRootEl,
    formEl,
    variant,
    previousVariant,
    product,
  } = e.detail;
});
document.addEventListener('theme:variant:change', (e) => {
  const {
    productRootEl,
    formEl,
    variant,
    previousVariant,
    product,
  } = e.detail;
});

theme:product:add ​

Dispatched when a product has been successfully added to the cart.

Event detail ​

  • cartItemCount: the number of items in the cart
  • itemsRootEl: the cart items’ container
  • lineItemEl: the cart item element
  • variantId: the ID of the variant that has just been added
  • key: the key of the line item
  • formEl: the form element that added the variant to the cart
  • cartPromise: a Promise that resolves to the updated cart object

Example ​

JavaScript
document.addEventListener('theme:product:add', (e) => {
  const {
    cartItemCount,
    itemsRootEl,
    lineItemEl,
    variantId,
    key,
    formEl,
    cartPromise,
  } = e.detail;
});
document.addEventListener('theme:product:add', (e) => {
  const {
    cartItemCount,
    itemsRootEl,
    lineItemEl,
    variantId,
    key,
    formEl,
    cartPromise,
  } = e.detail;
});

Getting updated cart state ​

Our themes do not fetch an updated cart object after a product has been added to the cart because we use the Section Rendering API to update the cart and related sections.

If you need the updated cart state, a cartPromise getter is available on the event’s detail object. This returns a promise that will resolve to the updated cart state.

JavaScript
document.addEventListener(
  'theme:product:add',
  async (e) => {
    const cart = await e.detail.cartPromise;

    console.log('Updated cart object', cart);
  }
);
document.addEventListener(
  'theme:product:add',
  async (e) => {
    const cart = await e.detail.cartPromise;

    console.log('Updated cart object', cart);
  }
);

Alternatively, you can get the updated cart object directly in your own listener for this event:

JavaScript
document.addEventListener('theme:product:add', async () => {
  const res = await fetch(
    window.theme.routes.cart_url,
    fetchConfigDefaults()
  );
  const cart = await res.json();

  console.log('Updated cart object', cart);
});
document.addEventListener('theme:product:add', async () => {
  const res = await fetch(
    window.theme.routes.cart_url,
    fetchConfigDefaults()
  );
  const cart = await res.json();

  console.log('Updated cart object', cart);
});

theme:line-item:change ​

Dispatched when a product that is already in the cart has had its quantity adjusted. Is also dispatched when a line item is removed (the quantity is 0).

Event detail ​

  • cartItemCount: the number of items in the cart
  • itemsRootEl: the cart items’ container
  • lineItemEl: the cart item element (null if item has been removed)
  • variantId: the ID of the variant that has just been added
  • key: the key of the line item
  • quantity: the new quantity of the line item
  • previousQuantity: the previous quantity of the line item
  • cart: the cart object

Example ​

JavaScript
document.addEventListener('theme:line-item:change', (e) => {
  const {
    cartItemCount,
    itemsRootEl,
    lineItemEl,
    variantId,
    key,
    quantity,
    previousQuantity,
    cart,
  } = e.detail;
});
document.addEventListener('theme:line-item:change', (e) => {
  const {
    cartItemCount,
    itemsRootEl,
    lineItemEl,
    variantId,
    key,
    quantity,
    previousQuantity,
    cart,
  } = e.detail;
});

theme:cart:change ​

This is a general event that is dispatched when the more specific theme:product:add or theme:line-item:change have been dispatched.

Event detail ​

  • type: the event type of the underlying event (theme:product:add or theme:line-item:change)
  • cartItemCount: the number of items in the cart
  • itemsRootEl: the cart items’ container
  • lineItemEl: the cart item element (null if item has been removed)
  • variantId: the ID of the variant that has just been added
  • key: the key of the line item
  • originalDetail: the detail object of the underlying event (see above for details)

Example ​

JavaScript
document.addEventListener('theme:cart:change', (e) => {
  const {
    type,
    cartItemCount,
    itemsRootEl,
    lineItemEl,
    variantId,
    key,
    originalDetail,
  } = e.detail;

  switch (type) {
    case 'theme:product:add':
      const { formEl } = originalDetail;
      break;
    case 'theme:line-item:change':
      const { quantity, previousQuantity, cart } =
        originalDetail;
      break;
  }
});
document.addEventListener('theme:cart:change', (e) => {
  const {
    type,
    cartItemCount,
    itemsRootEl,
    lineItemEl,
    variantId,
    key,
    originalDetail,
  } = e.detail;

  switch (type) {
    case 'theme:product:add':
      const { formEl } = originalDetail;
      break;
    case 'theme:line-item:change':
      const { quantity, previousQuantity, cart } =
        originalDetail;
      break;
  }
});

theme:cart:update ​

Dispatched when the cart has been manually updated following theme:update:cart (see Control events).

Because theme:update:cart does not modify cart contents, theme:cart:change is not dispatched on theme:cart:update, you need to listen for this event separately.

Event detail ​

  • cartItemCount: the number of items in the cart
  • itemsRootEl: the cart items’ container
  • cartPromise: a promise that resolves to the updated cart object (see Getting updated cart state under theme:product:add for details)
JavaScript
document.addEventListener('theme:cart:update', (e) => {
  const { cartItemCount, itemsRootEl, cartPromise } =
    e.detail;
});
document.addEventListener('theme:cart:update', (e) => {
  const { cartItemCount, itemsRootEl, cartPromise } =
    e.detail;
});

theme:cart-drawer:opening, theme:cart-drawer:open, theme:cart-drawer:closing, theme:cart-drawer:closed ​

These events are dispatched when the cart drawer is opening and closing, at the beginning and end of the transitions.

Event detail ​

  • cartDrawerEl - the cart drawer root element

Example ​

JavaScript
document.addEventListener(
  'theme:cart-drawer:opening',
  (e) => {
    const { cartDrawerEl } = e.detail;
  }
);

document.addEventListener(
  'theme:cart-drawer:open',
  (e) => {
    const { cartDrawerEl } = e.detail;
  }
);

document.addEventListener(
  'theme:cart-drawer:closing',
  (e) => {
    const { cartDrawerEl } = e.detail;
  }
);

document.addEventListener(
  'theme:cart-drawer:closed',
  (e) => {
    const { cartDrawerEl } = e.detail;
  }
);
document.addEventListener(
  'theme:cart-drawer:opening',
  (e) => {
    const { cartDrawerEl } = e.detail;
  }
);

document.addEventListener(
  'theme:cart-drawer:open',
  (e) => {
    const { cartDrawerEl } = e.detail;
  }
);

document.addEventListener(
  'theme:cart-drawer:closing',
  (e) => {
    const { cartDrawerEl } = e.detail;
  }
);

document.addEventListener(
  'theme:cart-drawer:closed',
  (e) => {
    const { cartDrawerEl } = e.detail;
  }
);