Developers

JavaScript events

JavaScript events The theme 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 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 the theme 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. The theme configures it so your calls render in the theme's own drawer and header, with no page reload. // Add to cart. Updates the theme'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 the theme'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 }], }); // The theme 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, the theme 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. Like any section, it can read the page's resource: on a product page your code can output the current product, and on a collection page the current collection. 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 and reads the page's resource the same way. 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. 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 live in the header, footer, or an overlay area, where the section cannot go. 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.

How the theme is built for AI

How the theme is built for AI The theme is built so that an AI coding assistant can read it, understand it, and change it safely. That is not a bolt-on feature. It comes from how the theme itself is structured. This article covers the parts of that structure that matter when you edit the theme with an AI assistant. To set an assistant up and start editing, see Edit the theme with AI assistants. Blocks inside blocks The theme is built on Shopify's newest theme architecture, where blocks nest inside other blocks. A section holds groups, a group holds columns, and a column holds text, buttons, images, and more. Most new designs are a fresh arrangement of blocks that already exist, not new code. An assistant composes these building blocks the same way you would in the editor, so the result behaves like the rest of the theme. One set of design tokens Colors, typography, and spacing are defined once, as theme-wide values, and every section reads from them. The theme ships a fixed set of typography presets and color schemes that all components share. When an assistant adds or changes something, it uses those same values, so the edit inherits your brand automatically instead of introducing a stray color or font. Clean, readable code the theme's markup is semantic and consistent, with structured data (schema.org) for products, articles, and breadcrumbs. Clean structure is easier for an assistant to read and edit precisely, with less guessing. That same structure also helps search engines and the new AI shopping assistants understand your store. Custom work is update-safe The theme is designed so your customizations live alongside it without being overwritten. New sections, blocks, and snippets are new files, and theme updates carry non-conflicting files over rather than erasing them. An assistant that follows this convention, which the free Elade AI kit sets as its first rule, leaves your custom work intact through updates. The kit hands this context over An assistant is only as good as what it knows about your theme. The free Elade AI kit is a set of instruction files (CLAUDE.md, AGENTS.md) and ready-made skills that describe all of the above to the assistant up front, so its edits match the theme's conventions from the first try. See Edit the theme with AI assistants to set it up.

AI skills for Claude Code

AI skills for Claude Code Skills are packaged workflows for AI coding assistants. Each one teaches the assistant a complete job on the theme: what to ask you, which files to touch, which rules to follow, and how to verify the result. They come free with the theme, part of the Elade AI kit at elade.io/ai-kit/freedom. This article assumes the base setup from Edit the theme with AI assistants (duplicated theme, pulled code, assistant installed). Install With Claude Code, add the plugin: claude plugin marketplace add elade-io/elade-ai-kit claude plugin install freedom@elade-ai-kit With Codex, add the marketplace, then run /plugins inside Codex and install Freedom from the Elade AI kit: codex plugin marketplace add elade-io/elade-ai-kit Manual alternative (no plugin): download the kit and copy the skills folders into .claude/skills/ (Claude Code) or .agents/skills/ (Codex) inside your theme folder. Both load skills from there too. How to use them Open Claude Code inside your theme folder (the one you pulled, with CLAUDE.md in it) and describe what you want in plain words. Keep a live preview running in a second terminal so you can watch each change land: shopify theme dev --store your-store.myshopify.com Claude picks the right skill on its own, or you can name it ("run personalize"). It asks any questions it needs, edits your local files, and shows you the result to review in that preview. When you are happy, check-and-push (or a manual shopify theme push) sends it to your duplicate, and you publish from Shopify admin. The full flow is in Edit the theme with AI assistants. New to the kit? Start with personalize to replace the demo copy with your own. The plugin installs the skills for every Claude Code project, but they only do their job inside a theme folder, where CLAUDE.md gives Claude the theme's full rulebook. The skills new-section. Builds a new section. It first checks whether your idea is achievable by composing the theme's existing blocks (no code, fully update-safe), and only then writes a new section file that follows the theme's architecture: correct settings vocabulary, design tokens, reveal animations, and a preset so the section appears in the editor picker. Try: "Use new-section to build a press logos strip with a heading and five logos." new-block. Builds a new reusable block you can place inside any section, group, or column. Same architecture guarantees as above. Try: "Use new-block to create a stat counter block: big number, label under it." personalize. Interviews you about your brand (voice, selling points, policies), then replaces the theme's placeholder copy with your real copy across the home page and templates, keeping the designed layout intact. Your answers are saved to STORE.md, so you are never asked twice. Try: "Run personalize, home page first." translations. Keeps the theme's six built-in languages complete and consistent: finds missing strings, adds translations for your custom sections, and reuses the theme's existing vocabulary in each language. Try: "Check translations after the changes we made this week." check-and-push. The safety gate before deploying. Runs the theme checks, sweeps for the silent failures Shopify only catches at upload, pushes to your duplicate theme, and verifies the output honestly (the Shopify CLI can report success even when a file failed). Try: "Run check-and-push." after-update. Runs after you update the theme to a new version. It reads the customizations log in STORE.md, checks every custom file, code edit, and added translation against the updated theme, and restores anything the update dropped. Try: "We just updated the theme. Check my customizations." Notes - Skills never edit your published theme; everything targets the duplicate you point them at. - Skills log their work (new files, decisions you made) in STORE.md next to the theme code. Keep that file: it is the shared memory across sessions and across AI tools. - Assistants without skill support: the same knowledge ships in the kit's AGENTS.md, so you can ask for the same jobs in plain words ("create a new section like new-section describes").

Edit the theme with AI assistants

Edit the theme with AI assistants This guide sets you up to change your theme by describing what you want to an AI assistant in plain English. You do not need to know how to code. You copy and paste a few commands, and the assistant does the editing. Everything happens on a copy of your theme, so your live store is never at risk. You publish the copy yourself at the end, once it looks right. For why the theme works so well with AI, see How the theme is built for AI. What you need - Your Shopify store login. - A computer running macOS or Windows. - About 30 minutes for this one-time setup. After that, changes take minutes. The steps below install a few free tools, make a safe copy of your theme, and hand that copy to your assistant. Step 1: Open a terminal The terminal is a plain text window where you paste commands. It already comes with your computer. - macOS: press Command and Space together, type Terminal, and press Enter. - Windows: click Start, type Terminal, and press Enter. On older versions of Windows, type PowerShell instead. Leave this window open. Every command below is pasted here, one line at a time, each followed by Enter. Step 2: Install the tools Node.js. This is a small runtime that the Shopify tool needs. Download the version labelled LTS from nodejs.org and install it like any other app. Shopify CLI. This is how your computer talks to your store. Paste this into the terminal: npm install -g @shopify/cli@latest On macOS you can use Homebrew instead, if you have it: brew tap shopify/shopify && brew install shopify-cli. Full instructions and other systems: Shopify CLI. Check it installed: shopify version A version number means you are ready. An AI assistant. Install one of these and sign in: - Claude Code - Codex Step 3: Make a safe copy of your theme Never point an AI assistant, or any code change, at your live theme. Make a copy first. In Shopify admin, go to Online Store > Themes. Find your theme, open the ... menu, and choose Duplicate. Your live theme keeps running and stays untouched, which makes it your backup. All of the work happens on the copy. Step 4: Download the copy to your computer The assistant edits your theme's files on your computer, so you need those files locally. In the terminal, move to a folder where you keep things (your Desktop works), then download the copy: cd Desktop shopify theme pull --store your-store.myshopify.com Replace your-store.myshopify.com with your own store address. The first time, a browser window opens so you can log in. The tool then lists your themes: choose the duplicate you just made. It downloads into a new folder named after the theme. Step 5: Connect your assistant to Shopify Shopify publishes an official AI toolkit that gives your assistant Shopify's documentation and a way to check its own work. Install it once: # Claude Code claude plugin install shopify-ai-toolkit@claude-plugins-official # Codex codex plugin add shopify@openai-curated Other editors, such as Cursor and VS Code: Shopify AI toolkit. Step 6: Add the Elade AI kit The Elade AI kit is what teaches your assistant how this theme is built. It comes in two parts. The instruction file. Everyone needs this. Download it from elade.io/ai-kit/freedom and put it in the folder you downloaded in step 4: - CLAUDE.md if you use Claude Code. - AGENTS.md if you use Codex or another assistant. It is the same content under a different filename. This one file gives the assistant the theme's full rulebook: how to build sections by composing blocks, how to keep your work safe through theme updates, and the mistakes that Shopify only reports at upload time. The skills. Optional. On top of the file, you can install six ready-made workflows for new sections, new blocks, brand copy, translations, safe deploys, and recovery after theme updates. In Claude Code: claude plugin marketplace add elade-io/elade-ai-kit claude plugin install freedom@elade-ai-kit In Codex, add the marketplace, then run /plugins inside Codex and install Freedom from the Elade AI kit: codex plugin marketplace add elade-io/elade-ai-kit See AI skills for what each one does. Assistants without skill support still get the whole kit from the instruction file, since the same knowledge is written into it. Step 7: Make your changes Move into the theme folder from step 4 (type cd followed by the folder name), then start a live preview: shopify theme dev --store your-store.myshopify.com This gives you a private preview link and updates it as changes happen. It runs on a temporary copy and never touches your live store. Now start your assistant in the same folder and tell it what you want. The best requests describe the goal, not the code: - "Add a section with three numbered steps: a photo on the left, a heading and text on the right. Match the theme's look." - "Our brand voice is warm and direct. Rewrite the home page copy and keep the layout." - "Make the footer newsletter heading smaller on mobile." Step 8: Push and publish The preview shows your changes, but they still live only on your computer. Two steps put them online. First, upload your changes to the copy: shopify theme push --store your-store.myshopify.com Choose the same duplicate theme when asked. The copy in your admin now has your changes. Then, in Shopify admin under Online Store > Themes, open the copy, review it one more time, and press Publish. Your previous theme stays in the theme list as a backup you can switch back to at any time. Ground rules - Work on the copy, always. Publishing is your manual, final step. - If someone edits the theme in the theme editor while you work, run shopify theme pull before you push. A push replaces what is online with the files on your computer. - The kit keeps a STORE.md file next to the instructions: your brand facts, language choices, and a log of every change. Leave it in the folder. It is how the next session, or the next assistant, remembers your store. - Theme updates: because the kit keeps custom work in new files, an update carries it over. The STORE.md log lists everything that changed, so nothing gets lost.