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.
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@themeblocks:main-product,featured-product,main-article,image-with-textandrich-text.@appblocks:main-product,featured-product,main-cart,cart-drawerandapps. - CSS variables are set on
:rootinsnippets/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-1and 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. |