Shopify’s theme editor gives merchants powerful control over their storefront. But the sections that appear in that editor, the building blocks merchants drag, drop, and configure, are all built by developers in Liquid and JSON.
If you want to add a custom promotional banner, a feature comparison table, a testimonial carousel, or any other reusable UI component to a Shopify theme, you need to build it as a custom section.
This guide walks you through everything you need to know about Shopify custom sections: what they are, how they are structured, how to write the Liquid template and JSON schema, and how to make them fully editable in the theme editor without writing a single line of JavaScript.
What Are Shopify Sections?
A section is a modular, reusable component of a Shopify Liquid theme. Each section lives in a single .liquid file inside the /sections folder of your theme.
Sections have two parts:
- The Liquid template – The HTML and Liquid code that renders the visible output
- The JSON schema – A block of JSON inside a
{% schema %}tag that defines all merchant-editable settings
When a merchant opens the theme editor, they see a panel of sections they can add, remove, rearrange, and configure. Every control in that panel, every text field, colour picker, image uploader, and toggle, is defined by you in the section’s JSON schema.
This is what makes shopify theme sections development so powerful. You write the structure once. Merchants customise the content without touching code.
Understanding Online Store 2.0 Sections Everywhere
Before Online Store 2.0, sections were only available on the homepage. Every other page used static templates that could not be customised through the theme editor.
Online Store 2.0 introduced sections everywhere. Custom sections can now be added to product pages, collection pages, blog posts, and any other page template. This dramatically expands what you can build without creating separate templates for every variation.
All modern Shopify themes, including Dawn and all themes released after 2021, support sections everywhere. If you are working with an older theme, consider upgrading before investing time in custom section development.
Our guide on Shopify Liquid optimisation covers the broader context of working with Liquid templates efficiently, which pairs directly with the section development techniques in this guide.
The Anatomy of a Custom Shopify Section File
A section file has the following structure:
<div class="custom-section"> <h2>{{ section.settings.heading }}</h2> <p>{{ section.settings.description }}</p> </div> {% schema %} { "name": "Custom Promo Banner", "tag": "section", "class": "custom-promo-banner", "settings": [ { "type": "text", "id": "heading", "label": "Heading", "default": "Welcome to our store" }, { "type": "textarea", "id": "description", "label": "Description", "default": "Add your promotional message here." } ], "presets": [ { "name": "Custom Promo Banner" } ] } {% endschema %}
Everything between {% schema %} and {% endschema %} is your JSON configuration. Everything above it is your Liquid template that uses section.settings.id to output the values merchants set in the editor.
Step 1: Create a New Section File
In your Shopify Admin:
- Go to Online Store > Themes
- Click the three-dot menu on your active theme
- Select “Edit code”
- Find the
/sectionsfolder in the file tree - Click “Add a new section”
- Name it using lowercase letters and hyphens only, for example
custom-promo-banner - Shopify creates the file with a basic template to start from
Always back up your theme before adding new files. Our guide on Shopify theme version control explains how to duplicate your theme and manage code changes safely so you always have a working version to return to.
Step 2: Build Your Liquid Template
Write the HTML structure of your section using standard HTML and Liquid syntax. Access merchant-set values using {{ section.settings.setting_id }}.
Example: A feature highlight section with an image, heading, and text
<section class="feature-highlight" style="background-color: {{ section.settings.background_color }};"> <div class="feature-highlight__inner"> {%- if section.settings.image != blank -%} <div class="feature-highlight__image"> {{ section.settings.image | image_url: width: 800 | image_tag: loading: 'lazy' }} </div> {%- endif -%} <div class="feature-highlight__content"> <h2>{{ section.settings.heading | escape }}</h2> <div>{{ section.settings.body_text }}</div> {%- if section.settings.button_label != blank -%} <a href="http://%20section.settings.button_url%20" class="btn"> {{ section.settings.button_label | escape }} </a> {%- endif -%} </div> </div> </section>
Keep your Liquid output clean. Use the escape filter on text inputs to prevent XSS injection, use image_url with explicit width parameters to ensure responsive images, and add loading: 'lazy' to images below the fold to protect your Core Web Vitals scores.
Our guide on Shopify Core Web Vitals explains how rendering choices inside custom sections directly affect your LCP and CLS scores.
Step 3: Write the JSON Schema
The schema block defines every setting that appears in the theme editor for your section. It must be valid JSON wrapped in {% schema %} and {% endschema %} tags.
Available setting types:
| Type | What It Renders in the Editor |
|---|---|
text |
Single-line text input |
textarea |
Multi-line text input |
richtext |
Rich text editor with formatting options |
html |
Raw HTML input |
image_picker |
Image upload and selection tool |
url |
URL input with optional link picker |
color |
Colour picker |
color_background |
Gradient and solid colour picker |
range |
Numeric slider with min, max, and step |
select |
Dropdown with predefined options |
checkbox |
Boolean toggle |
number |
Numeric input field |
video |
Shopify-hosted video picker |
font_picker |
Store font selector |
collection |
Collection picker |
product |
Product picker |
blog |
Blog picker |
page |
Page picker |
link_list |
Navigation menu picker |
Full schema example for the feature highlight section:
{% schema %} { "name": "Feature Highlight", "tag": "section", "class": "feature-highlight-section", "settings": [ { "type": "image_picker", "id": "image", "label": "Feature image" }, { "type": "text", "id": "heading", "label": "Heading", "default": "Why choose us" }, { "type": "richtext", "id": "body_text", "label": "Body text", "default": "<p>Describe your key feature or benefit here.</p>" }, { "type": "text", "id": "button_label", "label": "Button label" }, { "type": "url", "id": "button_url", "label": "Button URL" }, { "type": "color_background", "id": "background_color", "label": "Background colour", "default": "#ffffff" } ], "presets": [ { "name": "Feature Highlight" } ] } {% endschema %}
The presets array is required for the section to appear in the “Add section” panel in the theme editor. Without it, the section file exists in your theme but merchants cannot add it through the editor interface.
Step 4: Add Blocks for Repeatable Content
Blocks allow merchants to add multiple instances of a child element within a single section. A testimonial section with individually editable reviews is a classic blocks use case.
Schema with blocks:
{ "name": "Testimonials", "blocks": [ { "type": "testimonial", "name": "Testimonial", "settings": [ { "type": "textarea", "id": "quote", "label": "Quote", "default": "This product changed my life." }, { "type": "text", "id": "author", "label": "Author name", "default": "Happy Customer" }, { "type": "image_picker", "id": "avatar", "label": "Author photo" } ] } ], "max_blocks": 6, "presets": [ { "name": "Testimonials", "blocks": [ { "type": "testimonial" }, { "type": "testimonial" } ] } ] }
Rendering blocks in Liquid:
<div class="testimonials-grid"> {%- for block in section.blocks -%} <div class="testimonial-item" {{ block.shopify_attributes }}> <p>"{{ block.settings.quote | escape }}"</p> <span>{{ block.settings.author | escape }}</span> </div> {%- endfor -%} </div>
Always include {{ block.shopify_attributes }} on the block wrapper element. This attribute enables block selection highlighting in the theme editor, which lets merchants click directly on a block in the visual preview to edit its settings.
Step 5: Add the Section to a Page Template
With Online Store 2.0, sections can be added to any page template through the theme editor. However, you can also include sections statically in a template file using the {% section %} tag.
Dynamic addition (recommended): Open the theme editor, navigate to the target page, click “Add section,” and select your new section from the list.
Static inclusion in a template file:
{% section 'feature-highlight' %}
Use static inclusion only when the section must always appear on a specific template and should not be removable by merchants. For flexible layouts, dynamic addition through the editor is the better approach.
Step 6: Use Section Settings with Metafields
For advanced sections that pull dynamic product or collection data, you can combine section settings with Shopify metafields. This allows you to create sections that display product-specific content without hardcoding anything.
Our Shopify metafields guide covers how to define and access metafields in Liquid, which opens up powerful possibilities for data-driven section content on product and collection templates.
Performance Considerations for Custom Sections
Custom sections that load slowly or cause layout shifts hurt your store’s performance metrics. Keep these rules in mind:
| Performance Rule | Why It Matters |
|---|---|
| Always specify image dimensions | Prevents Cumulative Layout Shift (CLS) |
Use loading: 'lazy' on below-fold images |
Reduces initial page load time |
Avoid inline <style> blocks in section Liquid |
Use the assets folder for CSS instead |
Do not load JavaScript inside {% schema %} |
Use the {% javascript %} and {% stylesheet %} section tags |
| Keep Liquid logic minimal | Unnecessary loops slow render time |
For a broader performance audit process after adding custom sections, our speed optimisation checklist for Shopify stores walks through every check to run after theme changes.
Common Custom Section Mistakes to Avoid
Building Shopify JSON schema sections has a set of recurring errors that affect either the editor experience or the rendered output.
- Missing presets array. The section will not appear in the “Add section” panel. Merchants cannot add it dynamically through the editor.
- Duplicate setting IDs. Each setting within a section or block must have a unique
id. Duplicates cause silent failures where some settings do not save. - Not using
{{ block.shopify_attributes }}. Without this attribute, merchants cannot click on blocks in the visual preview to edit them. - Hardcoded content instead of settings. Content that should be editable by merchants through the theme editor should never be hardcoded in the Liquid template.
- Setting a maximum block value too high. An unrestricted block count allows merchants to add hundreds of blocks, which can cause performance issues on mobile.
These overlap with the broader category of errors covered in our post on Shopify technical mistakes that quietly cause problems in production.
Connecting Custom Sections to Your Store Design
Custom sections are most valuable when they serve a clear purpose within your overall store layout and conversion strategy. A feature highlight section on your homepage, a social proof block on product pages, or a comparison table on a landing page can each meaningfully lift engagement and conversion when placed correctly.
Our guide on building a high-converting Shopify homepage helps you understand which section types belong above the fold and how to sequence them for maximum conversion impact. For product pages specifically, our Shopify product page optimisation guide covers what sections and blocks drive the highest add-to-cart rates.
Before investing in custom section development, also consider whether a better-chosen theme already includes the section types you need. Our guide on how to choose the right Shopify theme covers what to evaluate before committing to theme customization work.
When to Choose Liquid Sections vs Hydrogen Components
If you are evaluating whether to build on standard Liquid or move to a headless Hydrogen architecture, custom sections are one of the strongest arguments for staying on Liquid. The theme editor, merchant customization, and full app ecosystem compatibility all depend on the Liquid section system.
Our comparison of Shopify Hydrogen vs Liquid gives you a clear framework for making that architecture decision based on your store’s actual requirements.
Get Professional Custom Section Development
Building custom sections correctly, with clean Liquid, a well-structured JSON schema, proper performance handling, and a polished editor experience, takes experience across both frontend development and Shopify’s theming system.
Our team at KolachiTech offers dedicated Shopify theme development services and Shopify custom development services for merchants who need bespoke sections and theme functionality built to a professional standard.
For merchants who need a complete custom storefront design alongside custom section development, our Shopify store design service covers the full visual and functional build from concept to launch.
Book a free consultation to discuss your specific section requirements and get a clear development plan.
Conclusion
Building custom Shopify sections with Liquid and JSON schema gives you complete control over what appears in the theme editor and how merchants interact with your theme. Each section file is self-contained, with the Liquid template handling the visual output and the JSON schema defining every merchant-editable field.
Start with a single simple section, get comfortable with the schema structure and setting types, then build up to sections with blocks, metafield integrations, and advanced conditional logic.
Done well, a library of custom sections becomes one of the most reusable and maintainable assets in your Shopify theme development toolkit.
Frequently Asked Questions
Q: What is a Shopify section?
A: A Shopify section is a reusable, modular component of a Liquid theme defined in a .liquid file. It contains both the HTML template and a JSON schema block that controls all merchant-editable settings visible in the theme editor.
Q: What is the difference between a section and a block in Shopify?
A: A section is a standalone component occupying a full area of a page. A block is a repeatable child element within a section, such as individual testimonial items within a testimonials section. Merchants can add, remove, and reorder both through the theme editor.
Q: Do custom Shopify sections work in Online Store 2.0 themes?
A: Yes. Online Store 2.0 introduced sections everywhere, which means custom sections can be added to any page template. All modern Shopify themes support this feature natively.
Q: Can I add custom sections to a Shopify theme without a developer?
A: Using existing sections through the theme editor requires no coding. Creating a new custom section from scratch requires editing theme files in Liquid and JSON, which requires developer knowledge.
Q: Where are section files stored in a Shopify theme?
A: All section files are stored in the /sections folder of your Shopify theme. Each section is a single .liquid file containing both the template and the schema.
Q: How do I add a custom section to a specific page in Shopify?
A: In Online Store 2.0 themes, open the theme editor, navigate to the target page, click “Add section” in the left sidebar, and select your custom section from the list. The section file must already exist in your theme’s /sections folder.
Q: What is the presets array in a Shopify section schema?
A: The presets array defines the default state of a section when first added through the theme editor. It also controls whether the section appears in the “Add section” panel. Without a presets entry, merchants cannot add the section dynamically through the editor.
