Developer reference

The storefront events Kera fires, the cart actions it supports, the window.Kera functions custom code can call, and how the theme is built.

.md View as Markdown

For developers adding custom code or apps. Kera follows Shopify's standard storefront events and actions, so code written for that standard works unchanged. Events are bubbling DOM events named shopify:*, heard on document. Actions live on window.Shopify.actions.

Events#

Event When Dispatched on
shopify:page:view Every page load. document
shopify:product:view A product page, quick view, Featured product section or product card is viewed. See the contexts below. A hidden element inside the product or card
shopify:product:select An option changes on the product page, Featured product section or quick view. Resolves with the variant, or null when the combination doesn't exist. The product's <product-info> element
shopify:collection:view Collection page load. A hidden element in the collection section
shopify:collection:update Filters or sort change. Resolves with productsCount. The filter form
shopify:search:update Search page load with a query, and filter or sort changes. Resolves with totalCount. The search section or the filter form
shopify:cart:view Cart page load (context: 'page') and each cart drawer open ('dialog'). A hidden element in the cart section or drawer
shopify:cart:lines-update Any add, quantity change or removal through the theme. action: add, update or remove. context: cart in the bag (including suggestions and the free gift), dialog in quick view, product elsewhere. The cart drawer, or the cart page section
shopify:cart:note-update The order note is saved. Same as above
shopify:cart:discount-update A discount code is applied or removed. A code that doesn't apply resolves with userErrors. Same as above
shopify:cart:error A cart request failed. Same as above

shopify:product:view contexts:

Where context When
Product page page Page load
Quick view dialog Each open
Featured product section page Once, when half on screen
Product card on the search page search Once, when half on screen
Product card on product and cart pages recommendation Once, when half on screen
Any other product card collection Once, when half on screen

Actions#

Action What the theme does
updateCart Shopify's default update, then redraws the bag and the header count.
openCart Opens the cart drawer, or goes to the cart page when Cart type is Page. Does nothing on the cart page.

Functions on window.Kera#

Function What it does
Kera.refreshCart() Redraws the bag and header count from the current cart. Returns a promise.
Kera.openCart() Same as the openCart action.
Kera.openDrawer() / Kera.closeDrawer() Opens or closes the cart drawer when it is on the page.
Kera.addToCart(body) Adds items in Ajax API format ({ items: [{ id, quantity, properties }] }), redraws the bag, fires shopify:cart:lines-update and follows After adding to the bag (Theme settings > Cart). Rejects with the cart's error message.
Kera.openQuickView(url, trigger) / Kera.closeQuickView() Opens quick view for a product URL, returning focus to trigger on close; or closes it. Without the Quick view section in Overlays, opening goes to the product page.
Kera.subscribe(topic, handler) Calls handler(payload) for each theme message on topic (see below). Returns a function that unsubscribes.
Kera.formatMoney(cents) Formats an amount in cents with the store's money format, for example formatMoney(15000).
Kera.fetchSections(ids, url) Renders the section IDs (an array) for url (default: the current page) with the Section Rendering API. Resolves with { id: html }.
Kera.routes, Kera.strings, Kera.template, Kera.moneyFormat, Kera.cartType Read-only values: Shopify routes, a few translated strings, the template name, the store's money format and Cart type.

Topics for Kera.subscribe:

Topic When Payload
cart:update The bag changed through the theme. The Ajax API cart object
cart:error An add failed. The Ajax API error (status, message, description)
drawer:open The cart drawer or quick view opens. 'cart' or 'quick-view'
drawer:close The cart drawer closes. 'cart'
variant:change A product form's variant changes. { variant, sectionId }
variant:media A variant change moves the gallery to its photo. { mediaId, sectionId }

Good to know#

How do I listen to an event?

Event data is on the event object. Most events carry a promise that settles once the change is complete; wait for it before reading the result.

document.addEventListener('shopify:cart:lines-update', async (event) => {
  const { action, context, lines } = event;
  const { cart, userErrors } = await event.promise;
  if (userErrors?.length) return; // Shopify declined the change, for example sold out
  console.log(`${action} from ${context}: the bag now holds ${cart.totalQuantity}`);
});

A change the cart declines (sold out, over a quantity limit) resolves with userErrors and cart: null. A request that fails (network down, server error) fires shopify:cart:error with code: 'SERVICE_UNAVAILABLE', and the promise rejects.

How do I update the cart with an action?
const { cart, userErrors } = await Shopify.actions.updateCart({
  lines: [{ merchandiseId: 'gid://shopify/ProductVariant/123456789', quantity: 1 }],
});
if (!userErrors?.length) Shopify.actions.openCart();
My code uses the Ajax cart API. How do I redraw the bag?

Call Kera.refreshCart() after /cart/add.js or /cart/change.js. The functions exist once the theme's scripts load, so check first, for example window.Kera?.refreshCart?.().

await fetch('/cart/add.js', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ items: [{ id: 123456789, quantity: 1 }] }),
});
await window.Kera.refreshCart();
window.Kera.openCart();
Where does the event data come from?

View events use Liquid's standard_event_data filter. Cart events are built from the Ajax cart response. Shopify's event library loads from cdn.shopify.com/storefront/standard-events.js; if it can't load, the theme works but fires none of these events.

The product form also fires cart:added on the <form> after a successful add, with no data, for older custom code. Use shopify:cart:lines-update instead. The theme listens to the editor's shopify:section:* and shopify:block:* events but doesn't fire them.

How is the theme built?
  • Blocks are private. All files in blocks/ start with _, so each block belongs to its section. Only these sections accept @theme blocks: main-product, featured-product, main-article, image-with-text and rich-text. @app blocks: main-product, featured-product, main-cart, cart-drawer and apps.
  • CSS variables are set on :root in snippets/css-variables.liquid: colors (--color-background, --color-text, --color-accent, --color-button, --color-border), type (--font-heading, --font-body, --size-h1 … --size-body), spacing (--space-1 … --space-9, --section-space, --page-margin, --page-max-width) and --radius.
  • Color schemes are classes: .color-scheme-1 and so on, from each scheme's ID. .color-mobile-<id> and .color-desktop-<id> apply a scheme on phones or from 750px only.
File What it holds
assets/standard-events.js Page view, view events and the search page load event.
assets/cart.js Cart events and the window.Kera cart functions.
assets/product.js Option changes (shopify:product:select).
assets/facets.js Filter and sort changes.
assets/product-card.js Card and Featured product views.
layout/theme.liquid The updateCart and openCart action setup, before content_for_header.
snippets/import-map.liquid Maps Shopify's event library.