Integration with the theme editor

When merchants customize sections, the HTML of those sections is dynamically added, removed, or re-rendered directly onto the existing DOM without reloading the entire page.

JavaScript that runs when the page loads will not run again when a section is re-rendered or added to the page. This poses a problem for any custom scripts that would need to be re-run.

Theme authors must also make sure that when a section or block is selected, that section or block is visible and remains visible while it is selected. A slideshow, for example, should slide to the block (slide) that is selected and pause while that block is selected.

To help with this, the editor fires DOM events within the context of the theme page (that is, the preview of the theme) which the theme's JavaScript should listen and react to:

type target detail bubbles cancelable Action Expected
shopify:section:load section {sectionId} yes no A section has been added or re-rendered. Re-execute any JavaScript needed for the section to work and display properly (as if the page had just been loaded).
shopify:section:unload section {sectionId} yes no A section has been deleted or is being re-rendered. Clean up any event listeners, variables, etc., so that nothing breaks when the page is interacted with and no memory leaks occur.
shopify:section:select section {sectionId,load} yes no User has selected the section in the sidebar. Make sure the section is in view and stays in view while selected (scrolling happens automatically).
shopify:section:deselect section {sectionId} yes no User has deselected the section in the sidebar.
shopify:section:reorder section {sectionId} yes no A section has been reordered.
shopify:block:select block {blockId,sectionId,load} yes no User has selected the block in the sidebar. Make sure the block is in view and stays in view while selected (scrolling happens automatically).
shopify:block:deselect block {blockId,sectionId} yes no User has deselected the block in the sidebar.

Events are triggered directly on section or block elements. In other words, event.target is the section or block element.

Section events are triggered on the <div> generated by Shopify. Block events are triggered on the elements that have the {{ block.shopify_attributes }}.

Events bubble up like other DOM events, such as click and keydown. This allows your scripts to listen for events using addEventListener or using a JavaScript library like jQuery. More information, like the section ID, is attached in event.detail. If you're using an older version of jQuery, you might have to use event.originalEvent.detail instead.

The event.detail.load property in the shopify:section:select and shopify:block:select events indicates whether the event is being triggered as part of a section re-render (i.e. after a shopify:section:load event), or following a selection by the user.

Ready to start selling with Shopify?

Try it free