JavaScript events

Use this page when you need behavior beyond Theme Editor settings but still want upgrade-safe customization.

Event strategy

• Prefer listening for existing lifecycle events before mutating DOM directly.
• Keep listeners idempotent so sections re-rendered by Shopify do not duplicate handlers.
• Scope behavior to section wrappers with data- attributes.

Typical hooks

• Product media and variant changes in assets/theme.js
• Cart drawer open/close and line-item updates; studio-arcana:cart:add fires after AJAX add even when Theme settings → Cart disables auto-open
• Collection pagination append events (load-more and infinite scroll)
• Navigation clicks: studioarcana:navigation (detail: type, label, parent, href, text) and dataLayer sa_navigation_click
• Quiz completion event: studio-arcana:quiz:complete (answers, scoreMap, resolvedProfileKey, recommendation with optional staffId)
• hollow-reserve:open — dispatched when shoppers click data-hr-reserve-staff controls (specialist team, service menu, quiz result CTA)
• studio-arcana:compare:change — fired when the compare tray changes; detail: { items: string[] } (up to 4 product handles from localStorage key sa_compare)
• studio-arcana:ritual:add-all — fired when a Ritual builder kit add-all succeeds; detail: { items: [{id, quantity}] }
• studio-arcana:upsell:click — fired when a cart upsell card is clicked; detail: { productHandle, variantId, source }
• studio-arcana:booking:click — fired when a service Book CTA is clicked; detail: { href, source: 'buybox' | 'sticky' }
• Lookbook analytics events: studio-arcana:lookbook:look-click, studio-arcana:lookbook:product-click, studio-arcana:lookbook:filter, studio-arcana:lookbook:load-more, studio-arcana:lookbook:quick-add

Implementation checklist

1. Listen in one bootstrap function.
2. Guard for missing nodes.
3. Rebind after Section Rendering API responses.
4. Fail silently for merchants without the optional section enabled.