Shopify Web Components in 2025 — The Complete Architecture Guide for Theme Devs

Web Components are a set of browser APIs — Custom Elements, Shadow DOM, and HTML Templates — that allow you to define reusable HTML elements with encapsulated behavior. Shopify themes use the Custom Elements API primarily: class ProductForm extends HTMLElement { ... } followed by customElements.define('product-form', ProductForm). The browser instantiates the class when the element appears in the DOM and calls lifecycle callbacks as it is connected, disconnected, or has attributes changed. This model maps well to Shopify sections — each section can be a self-contained custom element.

connectedCallback() is called when the element is inserted into the DOM — initialize event listeners, fetch data, and set up state here. disconnectedCallback() is called when the element is removed from the DOM — this is where you MUST clean up all event listeners, clear intervals, cancel fetch requests, and disconnect observers. This cleanup is not optional — missing it causes memory leaks that degrade store performance over time. attributeChangedCallback(name, oldValue, newValue) is called when observed attributes change — use for reactive attribute-driven behavior. constructor() is called when the element is created — never query the DOM here, as the element's children may not be attached yet.

A common Web Component bug: querying child elements in the constructor, getting null, and initializing incorrectly. The element's children are not attached when the constructor runs. Wait for connectedCallback: class HeroSlider extends HTMLElement { connectedCallback() { this.slides = this.querySelectorAll('.slide'); this.currentIndex = 0; this.setupControls(); } }. Note the use of this.querySelectorAll rather than document.querySelectorAll — always scope queries to the component using this to avoid selecting elements from other components.

Shopify sections can render on the same page multiple times. If the same section JavaScript is included twice, customElements.define() throws an error when called with an already-registered name. Always check before defining: if (!customElements.get('product-form')) { customElements.define('product-form', ProductForm); }. Dawn and Horizon both use this pattern. Without it, loading the same section JavaScript twice causes a NotSupportedError that breaks the entire component.