DEV Community

Cover image for Building a Custom Shopify Theme with Liquid: A Practical Guide
Pixel Mosaic
Pixel Mosaic

Posted on

Building a Custom Shopify Theme with Liquid: A Practical Guide

#ai #programming #cloud #performance

If you're building Shopify stores professionally, sooner or later you'll hit the limits of pre-built themes. While premium themes are excellent for getting started, custom themes give you complete control over performance, user experience, branding, and scalability.

In this guide, we'll build a custom Shopify theme using Liquid, Shopify's templating language, and cover the fundamentals you'll use in real-world projects.

Why Build a Custom Shopify Theme?

A custom theme isn't just about aesthetics—it's about creating an online store tailored to your business requirements.

Benefits include:

  • Faster page load times
  • Better Core Web Vitals
  • Fully customised layouts
  • Cleaner, maintainable code
  • Greater flexibility for future features
  • Improved SEO and accessibility

What You'll Need

Before you begin, make sure you have:

  • A Shopify Partner account
  • A development store
  • Node.js installed
  • Shopify CLI
  • Git
  • A code editor (VS Code works great)

Install the Shopify CLI:

npm install -g @shopify/cli @shopify/theme
Enter fullscreen mode Exit fullscreen mode

Verify the installation:

shopify version
Enter fullscreen mode Exit fullscreen mode

Step 1: Create a New Theme

Generate a new Shopify theme.

shopify theme init my-custom-theme
Enter fullscreen mode Exit fullscreen mode

Move into the project.

cd my-custom-theme
Enter fullscreen mode Exit fullscreen mode

Connect it to your development store.

shopify theme dev
Enter fullscreen mode Exit fullscreen mode

The CLI automatically watches for changes and reloads your browser.

Understanding Theme Structure

A Shopify theme typically contains:

assets/
config/
layout/
locales/
sections/
snippets/
templates/
Enter fullscreen mode Exit fullscreen mode

Here's what each folder does:

Folder Purpose
assets CSS, JavaScript, fonts, images
layout Main theme layout
sections Reusable page sections
snippets Small reusable components
templates Page templates
config Theme settings
locales Translation files

Keeping components modular makes your theme easier to maintain.

Step 2: Understanding Liquid

Liquid combines HTML with dynamic Shopify data.

Example:

<h1>{{ product.title }}</h1>

<p>{{ product.price | money }}</p>
Enter fullscreen mode Exit fullscreen mode

Here:

  • {{ }} outputs data
  • {% %} contains logic
  • | applies filters

Variables 

{{ product.vendor }}

{{ product.type }}

{{ product.available }}
Enter fullscreen mode Exit fullscreen mode

Conditions 

{% if product.available %}
  <p>In Stock</p>
{% else %}
  <p>Sold Out</p>
{% endif %}
Enter fullscreen mode Exit fullscreen mode

Loops

Display all products from a collection.

{% for product in collection.products %}

<h2>{{ product.title }}</h2>

{% endfor %}
Enter fullscreen mode Exit fullscreen mode

Step 3: Create Your First Section

Create:

sections/hero.liquid
Enter fullscreen mode Exit fullscreen mode

Example:

<section class="hero">

<h1>{{ section.settings.heading }}</h1>

<p>{{ section.settings.description }}</p>

</section>

{% schema %}
{
  "name": "Hero",
  "settings": [
    {
      "type": "text",
      "id": "heading",
      "label": "Heading"
    },
    {
      "type": "textarea",
      "id": "description",
      "label": "Description"
    }
  ]
}
{% endschema %}
Enter fullscreen mode Exit fullscreen mode

Now merchants can edit the content directly from Shopify's Theme Editor.

Step 4: Create Reusable Snippets

Example:

snippets/product-card.liquid
Enter fullscreen mode Exit fullscreen mode 
<div class="product">

<h3>{{ product.title }}</h3>

<p>{{ product.price | money }}</p>

</div>
Enter fullscreen mode Exit fullscreen mode

Render it anywhere.

{% render 'product-card', product: product %}
Enter fullscreen mode Exit fullscreen mode

This avoids duplicated code.

Step 5: Optimise Images

Instead of:

<img src="{{ product.featured_image }}">
Enter fullscreen mode Exit fullscreen mode

Use Shopify's image filters.

{{ product.featured_image
| image_url: width: 800
| image_tag:
loading: 'lazy'
}}
Enter fullscreen mode Exit fullscreen mode

Benefits:

  • Responsive images
  • Faster loading
  • Better Lighthouse scores

Step 6: Add Theme Settings

Create custom settings inside:

config/settings_schema.json
Enter fullscreen mode Exit fullscreen mode

Example:

{
  "name": "Brand Colours",
  "settings": [
    {
      "type": "color",
      "id": "primary",
      "label": "Primary Colour"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Access them anywhere.

{{ settings.primary }}
Enter fullscreen mode Exit fullscreen mode

Step 7: Improve Performance

A few easy wins:

Load JavaScript only when needed 

{{ 'product.js' | asset_url | script_tag }}
Enter fullscreen mode Exit fullscreen mode

Only include scripts on pages that require them.

Minimise CSS

Avoid shipping huge CSS frameworks.

Instead:

  • Split styles
  • Remove unused CSS
  • Compress assets

Lazy-load Images 

loading="lazy"
Enter fullscreen mode Exit fullscreen mode

A simple change that improves page speed significantly.

Step 8: Debug Liquid

Use Shopify CLI.

shopify theme dev
Enter fullscreen mode Exit fullscreen mode

The terminal reports Liquid errors immediately.

You can also inspect objects:

{{ product | json }}
Enter fullscreen mode Exit fullscreen mode

This is invaluable when exploring Shopify's data model.

Best Practices

✔ Keep sections modular

✔ Reuse snippets

✔ Avoid duplicated code

✔ Optimise images

✔ Keep JavaScript lightweight

✔ Use semantic HTML

✔ Test on mobile first

✔ Prioritise accessibility

Common Mistakes

Many developers make these errors:

  • Hardcoding content instead of using settings
  • Creating oversized sections
  • Loading every asset on every page
  • Ignoring image optimisation
  • Nesting Liquid logic excessively
  • Forgetting accessibility attributes

Small improvements here make a big difference over time.

Final Thoughts

Liquid is intentionally simple, but it's powerful enough to build fast, scalable Shopify themes that deliver excellent user experiences. By combining reusable sections, clean snippets, performance optimisation, and thoughtful architecture, you can create themes that are easier to maintain and adapt as a business grows.

Whether you're building a client project or your own eCommerce brand, mastering Liquid is one of the most valuable skills in the Shopify ecosystem.

Top comments (0)