Integrate sections with the theme editor

When merchants customize sections through the theme editor, the HTML of those sections is dynamically added, removed, or re-rendered directly onto the existing DOM, without reloading the entire page. However, any associated JavaScript that runs when the page loads won't run again.

Additionally, you must make sure that when a section or block is selected, that section or block becomes, and remains, visible while it’s selected. For example, a slideshow section should scroll into view when the section is selected, slide to a selected block (slide), and pause while that block is selected.

To help identify theme editor actions like section and block selection or reordering, you can use the JavaScript events emitted by the theme editor.

You might also want to prevent specific code from running in the theme editor. To do so, you can use Liquid and JavaScript variables for detecting the theme editor.

Section and block JavaScript events

The theme editor emits section and block JavaScript events that bubble, and are not cancellable. Each event has a target (event.target), which is either the associated section or block element. The section element is the Shopify generated section wrapper, and the block element is the element that has {{ block.shopify_attributes }} added to it.

The following table outlines the events:

type target detail Trigger Expected action
shopify:section:load section {sectionId} 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} 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
}
The user has selected the section in the sidebar. The theme editor automatically scrolls to the section, so make sure the section is in view, and stays in view, while selected.
shopify:section:deselect section {sectionId} The user has deselected the section in the sidebar.
shopify:section:reorder section {sectionId} A section has been reordered.
shopify:block:select block
{
blockId,
sectionId,
load
}
The user has selected the block in the sidebar. The theme editor automatically scrolls to the section, so make sure the block is in view, and stays in view, while selected.
shopify:block:deselect block
{
blockId,
sectionId
}
User has deselected the block in the sidebar.

In the table above, blockId represents the block ID, sectionId represents the section ID, and load indicates whether the event is being triggered by a section re-render, or a user selection. The value of load is true or false.

Detect the theme editor

You can detect whether you’re in the theme editor in Liquid and JavaScript.

Liquid

The global Liquid request object has a design_mode attribute that will return true if you’re in the theme editor, and false if not. For example:

JavaScript

In JavaScript, the global variable Shopify.designMode will return true if you’re in the theme editor, and undefined if not. For example: