Skip to main content
Merchants edit a theme in a visual builder: a form panel beside a live preview of their own store. The theme selects the editing shell and marks which elements are editable in place.

​
Editing shells

Set builder in theme.json.

full

Section tree, click-to-select on the canvas, drag to reorder, SEO panel, nested block editing. The default.

simple

One scrolling column of forms. No section tree, no click-to-select, no SEO panel. Nested blocks are displayed but not editable.
simple suits a theme small enough that a section tree adds overhead, such as a link-in-bio layout consisting of a profile and a list of links. The value is presentation only. Both shells call the same endpoints with the same scopes and the same concurrency control, and the server does not read it. It grants and restricts nothing. An unrecognised value resolves to full, including a typo, a wrong type or an absent key. Resolving to full shows extra controls; resolving to simple would hide them.

​
Inline editing

data-bs-edit makes an element editable in place on the canvas. Its value is the settings key written back to.
richtext makes the element contenteditable and stores HTML. image is not edited inline and opens the field in the panel instead.
data-bs-section, data-bs-section-type, data-bs-group and the wrapper around each {blocks} child are injected by the platform. Do not write them in a template.

​
Live theme settings

The builder applies theme setting changes to the preview without a reload. For an accent colour it calls a function the theme defines:
A theme with an accent setting that does not define this has no live preview for it. The merchant’s colour change is not visible until reload.
Accent CSS custom properties must hold RGB channels, not a hex string:
A hex value satisfies plain rgb(var(--accent)) and produces invalid CSS as soon as an opacity modifier is applied. The failure is silent.

​
The preview

The preview renders the theme against the merchant’s own data, on the store’s origin, in an iframe.
  • Drafts render through an uncached path, so preview updates are immediate while the live store lags by up to a minute.
  • The preview is cross-origin from the builder. Communication across that boundary goes through the platform’s bridge, not through theme code.