API for apps and custom code

Compatibility

The methods & events on this page are available on the following versions of our themes:

Beyond - versions 2.6.1 and up
Blockshop - versions 8.6.1 and up
Maker - versions 7.6.1 and up
Emerge - versions 5.6.1 and up

Page loaded

We wait to reveal much of the page until the DOM has fully loaded to allow asyncronous JavaScript a chance to initialize. It is recommended to hook into our ready event once the page has been unveiled:

window.addEventListener('theme:loaded', () => {
  // add callback code here
});

Cart updated

We use an Ajax cart that refreshes all products and the total when a quantity has been changed, or an item has been removed/added to the cart.

If you’re modifying cart markup you’ll need to do so after it has been updated:

window.addEventListener('theme:cart:updated', ({ detail: cart }) => {
  console.log(cart);
});

The event returns the updated cart , a DOM element object you can use to select updated cart items.

Product added to cart

Products can be added to the cart via Add to cart buttons, or Quick add buttons. In either case, you can use the following to listen to those events:

window.addEventListener('theme:cart:productAdded', ({ detail: variantId }) => {
  console.log(variantId);
});

The variant ID of the added item is returned.

Product variant changed

Triggered when a product’s variant has changed:

window.addEventListener(
  `theme:product:${productId}:variantUpdated`,
  ({ detail: { variant } }) => {
    console.log(variant);
  }
);

Where productId is defined (usually extracted from Liquid) as the following:

{% assign productId = product.id | append: '-' | section.id %}

Legacy callback

Please see the legacy variantUpdated callback below for the following versions:

Beyond - versions below 3.0.0
Blockshop - versions below 9.0.0
Maker - versions below 8.0.0
Emerge - versions below 6.0.0

window.addEventListener(
  'theme:product:variantUpdated',
  ({ detail: { section, variant } }) => {
    console.log(section, variant);
  }
);

The section DOM object the product belongs to, as well as the product variant is returned.

We’ve included the section object in case you need to properly scope multiple products on the same page.

Collection or search filtering finished

Triggered when the Collection page or Search products results page has been reloaded after a filter has been applied:

window.addEventListener('theme:navigation:reloaded', () => {
  // add callback code here
});

Triggered when the modal is opened:

window.addEventListener('theme:modal:opened', () => {
  // add callback code here
});

Triggered when the modal is closed:

window.addEventListener('theme:modal:closed', () => {
  // add callback code here
});

Drawer events

We include events for the drawer based on the following convention:

window.addEventListener(`theme:drawer:${side}:${status}`, () => {
  // add callback code here
});

Where side is one of left, right, or top. While status is one of opening, opened, closing, or closed.

Legacy drawer

Please see the legacy drawer methods below for the following versions:

Beyond - versions below 3.1.0
Blockshop - versions below 9.1.0
Maker - versions below 8.1.0
Emerge - versions below 6.1.0

We include individual events for each drawer (right/left) as well as transitory states if you need to add something to the drawer before it fully opens/closes.

The following is triggered before the right drawer closes:

window.addEventListener('theme:offCanvas:rightClosing', () => {
  // add callback code here
});

The following is triggered before the left drawer closes:

window.addEventListener('theme:offCanvas:leftClosing', () => {
  // add callback code here
});

The following is triggered after the right drawer is closed:

window.addEventListener('theme:offCanvas:rightClosed', () => {
  // add callback code here
});

The following is triggered after the left drawer is closed:

window.addEventListener('theme:offCanvas:leftClosed', () => {
  // add callback code here
});

The following is triggered before the right drawer opens:

window.addEventListener('theme:offCanvas:rightOpening', () => {
  // add callback code here
});

The following is triggered before the left drawer opens:

window.addEventListener('theme:offCanvas:leftOpening', () => {
  // add callback code here
});

The following is triggered after the right drawer is opened:

window.addEventListener('theme:offCanvas:rightOpened', () => {
  // add callback code here
});

The following is triggered after the left drawer is opened:

window.addEventListener('theme:offCanvas:leftOpened', () => {
  // add callback code here
});

Manually close drawer

We offer methods to close the right and left drawers:

theme.off_canvas.closeLeft()
theme.off_canvas.closeRight()

Swipe detection

Our themes include functionality to detect horizontal swipe events:

window.addEventListener('theme:swipe:left', () => {
  // add 'left' swipe callback code here
});

window.addEventListener('theme:swipe:right', () => {
  // add 'right' swipe callback code here
});