Custom Liquid Sections on Shopify: When to Write Code, and When Not To

A Liquid section is a block of theme code that merchants can place, reorder and configure from the theme editor, without touching the code. Built well, it is fast, durable and easy to edit. Built badly, it duplicates what the theme already does and slows every page it touches. The question is not whether to write custom sections, but which ones are worth the effort.

A section is worth building when

• The layout is specific to your brand and no existing section can produce it without hacks.
• Merchants need to edit the content themselves, and the settings can be clearly named.
• The section replaces two or three apps that were doing one job each.
• You can keep its markup and scripts small enough to add no meaningful weight to the page.

A section is not worth building when

If an existing section or a native theme setting already does the job, use it. A custom build that repeats a built-in feature is more code to maintain, and every extra script adds to the page weight that speed work has to clean up later. The same applies to a feature that only one page needs, which is often better as a snippet on that page.

How the pieces fit together

A section lives in the theme's sections folder and declares its settings in a schema. The schema is what makes it editable in the theme editor, so name settings in plain language your team will understand. Shopify's theme architecture documentation and the Liquid reference are the authoritative sources for the exact syntax and the available objects.

1. 01Start from an existing section that is close to what you need, so you inherit its structure.
2. 02Keep the markup semantic and accessible, with real headings and labelled images.
3. 03Load any script only where the section appears, and only if the section needs it.
4. 04Expose only the settings a merchant genuinely needs, to keep the editor simple.
5. 05Test it on mobile, with the theme editor open, and with real products and empty states.

Keep custom code fast

Every custom section is a place where speed can go wrong. Avoid large images that are not sized, avoid scripts that run before the page is interactive, and avoid anything that blocks rendering. Check the page after you add a section with the same PageSpeed method used in our speed guide, so you can see the cost before it reaches your customers.