Theme JS and events

Symmetry is one of the world's most popular premium Shopify themes aimed at empowering merchants to create a Shopify store that exudes a high-end brand appeal. Built using web components, it offers a highly modular architecture that makes customisation and maintenance both easier and more versatile than ever before.

In addition, Symmetry is optimized for speed, ensuring stores run as fast as possible to provide  customers with a seamless shopping experience.

The following guide is not intended as general user guidance. It is important to note that we do not offer general support on any custom development to our themes, or provide assistance on leveraging any of the items outlined below.

Custom JavaScript events

Symmetry broadcasts many custom events for ease of extensibility, detailed in this section.

If you would like to add your own JS to Symmetry we recommend using the custom.js file supplied with the theme and referencing it using Theme settings > Advanced > Custom HTML.

As a brief overview, Symmetry:

• Broadcasts many JS events
• Is built using web components
• Leverages 'code splitting' for some features
• Is completely custom built (no JS libraries)
• Has a number of JS utilities

Events are named in the following convention:

[on/dispatch]:[subject]:[action] 

Where dispatch will trigger an event to occur and on indicates an event has occurred.

All return data detailed in this section is returned within the event.detail object.

Tip: When in the Theme Editor, the details of each custom event will be logged out in the Dev Tools console every time one is triggered.

The available events are:

on:variant:change
on:cart:add
on:cart:error
on:cart:after-merge
on:cart-drawer:before-open
on:cart-drawer:after-open
on:cart-drawer:after-close
on:quickbuy:before-open
on:quickbuy:after-open
on:quickbuy:after-close
dispatch:cart-drawer:open
dispatch:cart-drawer:refresh
dispatch:cart-drawer:close
on:debounced-resize
on:breakpoint-change

on:variant:change

Fires whenever a variant is selected (e.g. product page, quick buy, featured product etc).

How to listen:

document.addEventListener('on:variant:change', (event) => {
// your code here
});

Returned data:

• form: the product form content
• variant: the selected variant object
• allVariants: an array of all variants
• selectedOptions: an array of currently selected options (e.g. ['Blue', 'Large'])

on:cart:add

Fires when a variant has been added to the cart, where it didn’t exist in the cart before. This event does not fire when the added variant was already in the cart.

How to listen:

document.addEventListener('on:cart:add', (event) => {
// your code here
});

Returned data:

• variantId: id of the variant that was just added to the cart

on:cart:error

Fires when an action related to the cart has failed, for example adding too much quantity of an item to the cart.

How to listen:

document.addEventListener('on:cart:error', (event) => {
// your code here
});

Returned data:

• error: the error message

on:cart:after-merge

Fires after a list of cart items has finished being dynamically updated after a cart change.

How to listen:

document.addEventListener('on:cart:after-merge', (event) => {
// your code here
});

on:cart-drawer:before-open

Fires before the cart drawer opens.

How to listen:

document.addEventListener('on:cart-drawer:before-open', (event) => {
// your code here
});

on:cart-drawer:after-open

Fires after the cart drawer has finished opening.

How to listen:

document.addEventListener('on:cart-drawer:after-open', (event) => {
// your code here
});

on:cart-drawer:after-close

Fires after the cart drawer has finished closing.

How to listen:

document.addEventListener('on:cart-drawer:after-close', (event) => {
// your code here
});

on:quickbuy:before-open

Fires before the quick buy drawer opens.

How to listen:

document.addEventListener('on:quickbuy:before-open', (event) => {
// your code here
});

on:quickbuy:after-open

Fires after the quick buy drawer has finished opening.

How to listen:

document.addEventListener('on:quickbuy:after-open', (event) => {
// your code here
});

on:quickbuy:after-close

Fires after the quick buy drawer has finished closing.

How to listen:

document.addEventListener('on:quickbuy:after-close', (event) => {
// your code here
});

dispatch:cart-drawer:open

Opens the cart drawer (if enabled in the theme settings).

How to trigger:

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

You can optionally pass in a detail object with a property of opener, which specifies the DOM element that should be focussed on when the drawer is closed.

Example:

document.getElementById('header-search').addEventListener('keydown', (evt) => {
   if (evt.keyCode === 67) {
      evt.preventDefault();
      document.dispatchEvent(new CustomEvent('dispatch:cart-drawer:open', {
         detail: {
            opener: evt.target
         }
      }));
   }
});

In this example, we attach a keydown listener to the search input in the header. If the user presses the c key, it prevents the default behaviour (which would be to type the letter c in the input) and dispatches the dispatch:cart-drawer:open event with a detail object that specifies the search input as the opener. When the cart drawer is closed, focus is returned to the search input.

dispatch:cart-drawer:refresh

Refreshes the contents of the cart drawer.

This event is useful when you are adding variants to the cart and would like to instruct the theme to re-render the cart drawer.

How to trigger:

document.dispatchEvent(new CustomEvent('dispatch:cart-drawer:refresh', {
bubbles: true
}));

dispatch:cart-drawer:close

Closes the cart drawer.

How to trigger:

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

on:debounced-resize

Fires when the viewport finishes resizing (debounced to 300ms by default).

How to listen:

window.addEventListener('on:debounced-resize', (event) => {
// your code here
});

on:breakpoint-change

Fires when the breakpoint of the viewport changes.

Example:

window.addEventListener('on:breakpoint-change', (event) => {
   if (theme.mediaMatches.md) {
       console.log(‘we are not on mobile’);
   }
});

Web components

Symmetry utilises web components to the fullest.

Web components are a set of standardised APIs that allow developers to create custom, reusable HTML elements that can be used across different web pages and applications. They consist of three main things: custom elements, shadow DOM and HTML Templates.

See the Mozilla Web Component documentation for more.

Third party JavaScript dependencies

Symmetry has no third-party JavaScript dependencies.