Shopify Custom Sections: The Complete Guide

A custom section is how you shape a Shopify storefront past the layout your theme ships with — a hero, a review grid, an FAQ, a size chart, an upsell block. On an Online Store 2.0 theme, sections are the unit merchants add, reorder, and configure in the theme editor, and the unit developers reach for when a design needs something the theme does not already provide.

This is the hub for the whole topic. It explains what a section actually is, the three ways to add one and the trade-offs of each, the theme-update problem that quietly deletes a lot of hand-built work, and where to go next for the specific task you are trying to do.

What a Shopify section is

A section is a reusable, self-contained block of a page. Technically, it is a .liquid file in your theme's sections/ folder that pairs markup (Liquid and HTML) with a {% schema %} block. The schema is a small piece of JSON that declares the section's name and its editable settings — text fields, image pickers, color swatches, and so on.

That schema is what makes a section feel like a first-class part of Shopify. Once a section exists in the theme, it shows up in the theme editor's "Add section" menu. A merchant can drop it onto a template, fill in its settings, reorder it, and hide it — all without touching code. Sections can also contain blocks: smaller repeatable items (a single slide, one FAQ row, one testimonial) that a merchant adds and reorders inside the section.

A few related terms are worth separating early:

• Section — a configurable block you place on a page (what this guide is about).
• Template — the page-level file (templates/product.json, templates/index.json) that lists which sections appear on that page, and in what order.
• App block — a section-like unit rendered by an app rather than by a file in your theme. It appears in the same editor menu but lives outside your theme code. That distinction is what the theme-update section below turns on.

The three ways to add a section

There are three practical routes to a new section, and they differ mostly in how much control you get versus how much can break later.

The theme editor (no code)

Many themes already include flexible sections — often a "Custom Liquid", "Multicolumn", "Rich text", or "Image with text" section. You add one from the editor, configure its settings, and you are done. This is the fastest path and needs no development, but you are limited to what the theme's built-in sections expose. For a genuinely new layout, the settings usually will not stretch far enough.

Code (a section file in your theme)

For full control you write the section yourself: a new .liquid file in sections/, with your markup and a {% schema %} that defines exactly the settings you want. This is the most flexible route and the one most tutorials teach. The step-by-step is here: How to create a custom section in Shopify.

The catch is ownership: the file now lives inside your theme. That is fine until you update or replace the theme — which is the problem covered below.

An app

A section can also be delivered by a Shopify app as an app block or an app-embedded section, rendered through a Theme App Extension. You install the app, and its sections appear in the editor next to the theme's own. Because the markup lives in the app — not in your theme files — it is not touched when the theme is updated. This is the mechanism SectionGuard uses, and it is explained in depth in Shopify Theme App Extensions, explained.

The theme-update problem

Here is the issue that decides whether your work survives. When you add a section by editing theme files — a new .liquid file, or pasted markup inside a "Custom Liquid" box — that code becomes part of that specific theme version. Shopify does not merge your edits into a theme update. When you install a new version of the theme (or switch themes entirely), the update publishes a fresh copy of the theme's files, and anything you added by hand to the old copy is not carried over.

In practice that means a store owner can spend hours building a custom section, update the theme months later to get a bug fix or a new feature, and find the section gone. Section settings a merchant configured in the editor are stored per template, so those can be lost too if the section they referred to no longer exists.

There are two honest ways to avoid this:

1. Keep a disciplined update workflow — duplicate before updating, keep custom files in a documented list, and re-apply them to the new theme. This works but depends entirely on process. The full method is in Update your Shopify theme without losing customizations.
2. Render the section from outside the theme — via a Theme App Extension, so a theme update or swap never touches it. This is the approach we compare in detail in File-based vs. app-based sections.

Neither route is "correct" in the abstract. A one-off tweak on a theme you rarely touch is fine to hand-code. A section you rely on across theme changes is safer rendered from an app. The honest comparison lays out which survives a theme update and which survives an app uninstall, so you can choose with open eyes.

Where this goes next

The cluster guides below cover each task step by step. Start with the one that matches what you are doing:

• How to create a custom section in Shopify — build one from scratch, with the file, the schema, and example markup.
• How to add a section to a page — place an existing section on a template and configure it.
• How to add custom CSS to a section — style a section without breaking the rest of the theme.
• Section schema and blocks — a deeper reference for settings, blocks, and presets.

If your real question is "how do I keep these sections when I change themes", read Theme App Extensions alongside the comparison — together they explain why app-rendered sections survive updates that overwrite theme files, and where SectionGuard fits.