Appearance

Control events ​

The theme listens for these events, allowing you to control theme elements in a predictable way.

theme:change:option-values ​

This event is only available in Theme events v1.1 and later.

Dispatch this to the product root to programmatically change the current variant by providing an array of option values in the order of the options' positions.

If the options belong to a different product due to Combined listings, the page will update automatically to reflect the new product.

Target ​

Event detail ​

  • optionValueIDs: the IDs of the options values as an Array

Example ​

JavaScript
const productRootEl = document.querySelector(
  `[data-product-root="${shopifySectionId}"]`
);

productRootEl.dispatchEvent('theme:change:option-values', {
  detail: {
    optionValueIDs: [
      2034596413553,
      2034596544625,
      2034596708465,
    ]
  },
});

theme:change:variant ​

Dispatch this to the product root to programmatically change the current variant.

Target ​

Event detail ​

  • variantId: the ID of the variant as a Number

Example ​

JavaScript
const productRootEl = document.querySelector(
  `[data-product-root="${shopifySectionId}"]`
);

productRootEl.dispatchEvent('theme:change:variant', {
  detail: { variantId: 39577036324953 },
});

theme:update:cart ​

Dispatch this event to document to update all cart sections and trigger the cart update sequence. Sections updated: cart items, cart footer, cart item count, cart live region. Also triggers an update of any “Free shipping bar” sections.

Once the updates have been successfully completed, the theme:cart:update event will be dispatched (see Theme events).

This event does not modify the cart state, it only triggers an update to reflect changes that have already been made to the cart state. This event also does not open the cart drawer, you can do that with theme:open:cart-drawer.

Event detail ​

None.

Example ​

JavaScript
document.dispatchEvent(
  new CustomEvent('theme:update:cart')
);

Example: Opening cart drawer following a successful update ​

JavaScript
document.addEventListener('theme:cart:update', () => {
  document.dispatchEvent(
    new CustomEvent('theme:open:cart-drawer')
  );
});

document.dispatchEvent(
  new CustomEvent('theme:update:cart')
);

theme:open:cart-drawer, theme:close:cart-drawer ​

Dispatch these events to document to open and close the cart drawer.

Event detail ​

None.

JavaScript Example ​

JavaScript
document.dispatchEvent(
  new CustomEvent('theme:open:cart-drawer')
);

document.dispatchEvent(
  new CustomEvent('theme:close:cart-drawer')
);

Alpine.js Example ​

Liquid
<div x-data>
  <button @click="$dispatch('theme:open:cart-drawer')">
    Open cart drawer
  </button>
  <button @click="$dispatch('theme:close:cart-drawer')">
    Close cart drawer
  </button>
</div>