Building Custom Shopify OS 2.0 Sections: A Complete Developer Guide
The Power of OS 2.0 Sections
Shopify's Online Store 2.0 (OS 2.0) introduced JSON templates and the ability to add sections on every page — not just the homepage. This was a game-changer for both developers and merchants.
Why Custom Sections Matter
Pre-built theme sections are limiting. They're designed for the "average" store, but your store isn't average. Custom sections give you:
- •Pixel-perfect control over layout and design
- •Merchant self-service: Clients can edit content, reorder sections, and manage settings without touching code
- •Reusability: Build once, use across multiple pages and themes
- •Performance: Only load the CSS and JS that each section needs
Anatomy of a Custom Section
Every Shopify section has three parts:
Schema (JSON): Defines the settings that appear in the theme editor — text fields, image pickers, color selectors, etc.
Markup (Liquid + HTML): The actual template that renders the section content.
Styles (CSS): Scoped styles that only apply to this section.
Best Practices for Custom Sections
After building hundreds of custom sections, here are my key learnings:
- •Use blocks for repeatable content: Instead of hardcoding 3 testimonial cards, use blocks so the merchant can add, remove, and reorder them.
- •Preset sensible defaults: Every setting should have a useful default value so the section looks good out of the box.
- •Use metafields for complex data: Don't try to cram everything into section settings. Use metafields for structured product data.
- •Keep sections independent: Each section should be fully self-contained. Avoid cross-section dependencies.
- •Test on mobile first: Over 70% of e-commerce traffic is mobile. Design your sections accordingly.
Pro tip: Create a "section library" for each client — a documented collection of all custom sections with their settings, use cases, and screenshots. This becomes invaluable for ongoing maintenance and client training.