Developers

JavaScript events

JavaScript events Reign implements Shopify's Standard Storefront Events and Actions: the cross-theme interface that apps, analytics tools, and AI agents use to read and drive the storefront. You integrate against the standard once. It works on Reign without forking theme files, parsing markup, or intercepting network requests. The same code keeps working on any other theme that implements the standard. Two Shopify references define the contract: - Standard storefront events - Standard storefront actions Anything you find in the theme source that is not a shopify: event or a Shopify.actions call is internal wiring. It can change at any time, so do not depend on it. Listening for events Every event bubbles to document. Add a listener and read the event properties: document.addEventListener('shopify:cart:lines-update', (event) => { console.log(event.action, event.lines); // "add", "update", or "remove" event.promise?.then(({ cart }) => { console.log(cart.totalQuantity, cart.cost.totalAmount.amount); }); }); Events that describe an operation in progress (the cart mutations, variant selection, and the collection or search refresh) carry a promise. It resolves once the operation commits and gives you the canonical result: the updated cart, the selected variant, or the new product count. Read the promise when you need the final state rather than the optimistic one. Events Reign emits | Event | Fires when | |---|---| | shopify:page:view | every page load | | shopify:product:view | a product page loads | | shopify:product:select | the shopper changes a variant | | shopify:collection:view | a collection page loads | | shopify:collection:update | collection filters or sort change | | shopify:search:update | search filters or sort change | | shopify:cart:view | the cart drawer opens | | shopify:cart:lines-update | a line is added, updated, or removed | | shopify:cart:note-update | the cart note changes | | shopify:cart:discount-update | a discount is applied or removed | | shopify:cart:error | a cart operation fails | Payloads follow the Shopify Storefront GraphQL API shape: camelCase fields, and prices as money objects with amount and currencyCode. The full payload for each event is documented in Shopify's standard events reference linked above. Driving the cart Shopify injects a Shopify.actions object on every storefront. Reign configures it so your calls render in Reign's own drawer and header, with no page reload. // Add to cart. Updates Reign's drawer and header in place, no reload. const { cart, userErrors } = await Shopify.actions.updateCart({ lines: [{ merchandiseId: 'gid://shopify/ProductVariant/123', quantity: 1 }], }); await Shopify.actions.openCart(); // opens Reign's cart drawer const { cart: current } = await Shopify.actions.getCart(); // reads the current cart updateCart also emits the matching shopify:cart: events for you, so code that calls it does not need to dispatch them too. Always check userErrors before you use cart. Common examples Track add to cart in analytics document.addEventListener('shopify:cart:lines-update', (event) => { if (event.action !== 'add') return; event.promise?.then(({ cart }) => { myAnalytics.addToCart(cart); }); }); Update the cart from your own code await Shopify.actions.updateCart({ lines: [{ merchandiseId: 'gid://shopify/ProductVariant/123', quantity: 1 }], }); // Reign re-renders its cart drawer and header. No extra refresh call needed. React when a shopper picks a variant document.addEventListener('shopify:product:select', (event) => { event.promise?.then(({ variant }) => { if (variant) updateBadge(variant.availableForSale); }); }); Pause background media when the cart drawer opens document.addEventListener('shopify:cart:view', () => { video.pause(); });

Custom Liquid and HTML

Custom Liquid and HTML When you need code that no built-in setting covers, Reign gives you two ways to drop it onto a page: the Custom Liquid section and the Custom Liquid block. Both take Liquid, HTML, or an app snippet and render it in place. The difference is where the code sits and what it can read. Use the section for a standalone band of custom code, with its own width, spacing, and background. Use the block to place custom code inside another section, next to that section's content. Custom Liquid section A full-width section that renders whatever you type into one field. Add it from Add section under the Layout group. 1. In the theme editor, open the page where you want the code. 2. Click Add section. 3. Under Layout, choose Custom Liquid. 4. Open the section and paste your code into the Liquid field. You cannot add this section to the header, the footer, or an overlay group. For those areas, use the Custom Liquid block inside a section that already lives there. Settings - Liquid: the field that holds your code. Liquid, HTML, and app snippets all render here. The section runs at the page level, so it cannot read a product or collection on its own. To read the current resource, use the block instead (see below). This section also uses the standard Color, Layout, Size, Appearance, Border, Padding, Margin, and Visibility controls. See Common section settings. Custom Liquid block A block you add inside a section, alongside that section's other blocks. It appears in Add block under the Basic group. 1. In the editor, select the section you want the code in. 2. Click Add block. 3. Under Basic, choose Custom Liquid. 4. Drag it to the right spot in the section's blocks, then paste your code into the Liquid field. Settings - Liquid: the field that holds your code. Liquid, HTML, and app snippets all render here. The block runs inside its host section, so it can read the page's resource. On a product page it can reach the current product, and on a collection page the current collection, which lets you output values tied to what the shopper is viewing. The section version cannot do this. Which one to use - Reach for the section when the code is its own band of the page and you want background, width, and spacing controls around it. - Reach for the block when the code belongs next to existing content, or when it needs to read the current product or collection. Tips - The Liquid field renders code, so a typo can break the page or the editor preview. Keep a copy of what you paste so you can revert. - To add vertical space rather than code, you do not need a Custom Liquid section. Add the Spacing section (also under Layout), whose main control is Height. For spacing between blocks inside a section, see Common section settings.