Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 61 ยท Getting Started

The Theme Editor and How Merchants Use Your Theme

See the theme editor through a merchant's eyes: sections, blocks, settings, presets, previews, app blocks and JSON templates, and how to design for non-developers.

You write the code, but the person who uses it every day is the merchant. They never open your Liquid files. They open the theme editor (also called the theme customizer), a visual tool inside the Shopify admin where they add sections, change text and images, switch colors and preview pages on desktop and mobile. A theme that is pleasant to edit sells and gets recommended; a theme that forces merchants to ask a developer for every change does not.

This lesson tours the editor from the merchant's side and connects each thing they see to a file you write. The editor itself is part of Shopify's admin, so it cannot run here. Real theme code appears in read-only blocks, and two live stand-ins imitate the idea: one builds an editor panel from a schema, and one shows what a preset does when a section is added.

What the merchant sees

Open Online Store > Themes > Customize in the admin. The screen has three areas:

  • Left sidebar. A list of the sections on the current page, with groups for the header and footer. Click a section to see its settings and blocks. A second tab (or a "Theme settings" icon) holds global settings such as colors, typography and social links.
  • Top bar. A page picker (home, product, collection, cart and others), a device switcher for desktop and mobile preview, and the Save button.
  • Preview. Your storefront, rendered live with the merchant's actual products. Clicking an element in the preview selects the matching section in the sidebar.
flowchart LR
  subgraph Editor
    SB["Sidebar<br/>sections, blocks, settings"]
    PV["Preview<br/>live storefront"]
  end
  SB -->|"change a setting"| PV
  PV -->|"click an element"| SB
  SB -->|"Save"| J["JSON template and settings_data.json"]

The sidebar and preview talk to each other; Save writes the choices to JSON files in the theme.

The vocabulary: sections, blocks and settings

Everything in the sidebar maps to something in your code.

Sections are the large parts of a page: a banner, a product grid, a testimonial strip. A section is a Liquid file in sections/. The merchant can add, remove, hide and reorder sections on pages whose template is JSON.

Blocks are repeatable items inside a section: a slide in a slideshow, a column in a feature row, an item in an FAQ. Merchants add, remove and reorder them. Blocks are either defined inside the section's schema or are theme blocks from blocks/.

Settings are the individual controls: a text box, a color picker, a slider, an image picker. They exist at three levels: theme settings (global), section settings and block settings. You define them in JSON inside a {% schema %} tag (sections and blocks) or in config/settings_schema.json (theme).

A trimmed section schema looks like this (read-only; the next lessons teach every field):

LIQUID
{% schema %}
{
  "name": "Announcement",
  "settings": [
    { "type": "text", "id": "message", "label": "Message", "default": "Free shipping over $50" },
    { "type": "color", "id": "background", "label": "Background", "default": "#1a1a1a" }
  ],
  "blocks": [
    { "type": "link", "name": "Link", "settings": [
      { "type": "text", "id": "label", "label": "Label" },
      { "type": "url", "id": "url", "label": "Link" }
    ] }
  ],
  "presets": [{ "name": "Announcement" }]
}
{% endschema %}

Every label here is text the merchant reads. Treat those labels as part of your product's user interface. Building a Section and Schema Settings and Setting Types in Depth go through each part.

Stand-in: from schema to editor panel

The editor reads your schema and builds a form. This stand-in imitates that step with a text-based "panel". It handles only a few setting types, and the real editor has many more and a graphical interface. The point is that the form comes from data you write.

JS Stand-in: build an editor panel from a schema

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Presets and default content

A section only appears in the editor's "Add section" list if its schema has a preset. The preset gives the section a name in the picker and can set starting values and starting blocks, so the merchant does not face an empty box:

LIQUID
"presets": [
  {
    "name": "Announcement",
    "settings": { "message": "Welcome to our store" },
    "blocks": [ { "type": "link" }, { "type": "link" } ]
  }
]

Sections without presets can still be used if you place them yourself in a JSON template or a section group. This is common for main product and cart sections that every page of that type needs but merchants should not delete.

Themes can also ship style presets in settings_data.json (for example "Light", "Dark", "Warm"), so a merchant picks a look in one click. See Global Theme Settings.

Stand-in: what happens when a section is added

When a merchant clicks Add section, the editor creates a new unique id and writes an entry into the template's JSON. This stand-in does the same using a preset. The id format here is simplified; Shopify generates its own.

JS Stand-in: add a section from a preset

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Previewing and saving

Everything the merchant changes in the editor is a draft until they press Save. The preview shows the draft, and the editor keeps undo history. Saving writes to the theme's JSON: section choices go to templates/*.json and section groups, and theme-wide choices go to config/settings_data.json. Because the editor writes those files, your own changes to them can collide with a merchant's work. Version-control strategies are in Version Control and Team Workflows.

The preview loads your real theme with a special editor script. When a merchant adds or changes a section, the page does not fully reload. Shopify re-renders that section and replaces it. That means your JavaScript must handle sections appearing, changing and disappearing; Shopify fires events such as shopify:section:load for this, covered in JavaScript in Themes.

Merchants can also preview a theme at a unique URL before publishing, in a specific template (a product that uses an alternate template, for example), and inspect how the page looks on mobile.

App blocks and app embeds

Apps can appear in the editor in two ways:

  • App blocks are blocks an app provides. If your section schema allows the @app block type, merchants can add an app's block (a reviews widget, a subscription selector) inside your section, and move it like any other block.
  • App embeds are page-wide additions, such as a chat bubble or a cookie banner. They appear in a separate "App embeds" area of theme settings and are turned on and off by the merchant.

This is why OS 2.0 themes need less hand-edited code for apps. If you forget to accept @app blocks in a section, merchants cannot place app content there. App Blocks and App Embeds covers how to support them well.

Designing for non-developers

A theme's settings are its user interface. Some habits that make a theme easy to use:

  • Write labels for people. "Background color" beats "bg_col". Use short helper text (info) where a choice is not obvious.
  • Choose good defaults. A freshly added section should look good without any edits. Test every preset with no changes.
  • Do not overwhelm. A section with 40 settings is hard to use. Group related settings under header settings, hide settings that do not apply (visible_if), and prefer a few clear options over many tiny ones.
  • Handle empty states. If the merchant has not chosen an image or product, show a placeholder, not a broken layout.
  • Match the merchant's data. Offer dynamic sources so a heading can come from a metafield (see Metafields in Themes).
  • Make it hard to break. Use range and select instead of free text where only certain values work. Give required sections no delete option by placing them in the template instead of the picker.

Before you hand a theme to a merchant, open the editor yourself and try to build a page without reading any code. Everything awkward you notice is a bug in the theme, even if the Liquid is perfect.

JSON templates, from the merchant's side

For a merchant, a JSON template simply means "this page's layout is editable". On a product page they see the main product section with its blocks (title, price, buy button), then other sections below it, and they can add a testimonial section between them. They can also create alternate templates (for example "Product, long description") and assign them to individual products. You provide the possible layouts; the merchant picks and tunes them. The developer's side of this is in JSON Templates and Online Store 2.0.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What must a section have for it to show up in the editor's Add section list?

    The presets entry names the section in the picker and can supply starting settings and blocks. Without one, you can only place the section yourself.
  2. 2. Where do a merchant's theme-wide choices, like colors and fonts, end up after Save?

    The editor stores global setting values in config/settings_data.json. Section and block choices go into the JSON templates and section groups.
  3. 3. How can an app show content inside one of your sections in the editor?

    Apps provide app blocks, and merchants place them in sections that allow the @app type. App embeds are separate page-wide additions.
  4. 4. Which is a good practice for theme settings?

    Settings are the merchant's user interface. Clear labels and good defaults make the theme usable without a developer.

Summary

  • Merchants use the theme editor to edit sections, blocks and settings, previewing changes before they save.
  • Your schema defines the editor's form; presets define what appears in Add section and how it starts.
  • Saving writes JSON: templates and section groups for layout, settings_data.json for global settings.
  • App blocks and app embeds let apps appear in the editor; accept @app blocks in sections where they make sense.
  • Design settings like a product: clear labels, safe defaults, empty states and limited choices.

Now start learning the template language itself with Liquid Basics: Output, Objects and Whitespace.