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.

Manually update cart

Calling theme.cart.updateAllHtml() globally should re-render the cart if you’ve modified it’s contents via the API.

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 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/open drawer

We offer methods to toggle the right and left drawers:

theme.off_canvas.closeLeft()
theme.off_canvas.closeRight()
theme.off_canvas.openLeft()
theme.off_canvas.openRight()

Swipe detection

Our themes include functionality to detect swipe events broken down into four directions:

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

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

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

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