Right, so you’ve decided to bend the theme to your will. Excellent. This is where you stop merely using a theme and start making it truly yours. But with great power comes a somewhat confusing set of rules about what file takes precedence over what. The system is logical once you understand it, but the designers, in their infinite wisdom, decided that a simple numbered list was too straightforward. We navigate by pathnames instead.

The absolute bedrock principle you must internalize is this: specificity wins. The most specific, most directly applicable template file will always be used. The framework hunts for a template by following a path of increasing generality, and the first one it finds, it uses. Think of it like a very pedantic butler looking for instructions: he’ll check the exact room you’re in first, then the hallway, then the entire mansion’s rules, in that order.

The Template Lookup Dance

When you ask for a page, say the product page for your best-selling artisanal cheese board (/products/superior-cheese-board), the rendering engine performs a very specific search. It’s going to look for templates in this order, and use the first one it finds:

  1. Your custom view: templates/custom/my_special_product_view.liquid (if you’ve defined a custom view for that product in the admin).
  2. Your template override: templates/product.superior-cheese-board.liquid (a template suffixed with the product’s handle).
  3. Your base template: templates/product.liquid (the standard template for all products).
  4. The theme’s base template: Looks in the currently active theme’s files for templates/product.liquid.
  5. The default theme.liquid layout: If all else fails, it will just render the content inside the foundational layout/theme.liquid file. This almost never happens for core objects like products, but it’s the final fallback.

The key takeaway? The files in your local templates/ directory have the highest precedence. They override everything from the theme. This is your primary tool for customization.

How to Actually Override a Template

Let’s say you hate the theme’s product page. It’s fine for socks, but your cheese boards are a spiritual experience and deserve a more dramatic presentation. You’re going to override product.liquid.

First, you need to get the theme’s current template file. Use the Theme Commands:

theme get -t live -p templates/product.liquid

This pulls the live theme’s product.liquid file down into your local project structure. You’ll now see it at templates/product.liquid. Open it up. Make your glorious, cheese-centric changes.

{% comment %} templates/product.liquid {% endcomment %}
{% layout 'theme' %}

<div class="hero-cheese-experience">
  <h1>{{ product.title }}</h1>
  <p>Not just a board. A destiny.</p>
  {% render 'super-fancy-gallery' section: section %}
  {% comment %} ... your amazing custom code ... {% endcomment %}
</div>

Now, when you run theme serve, your local templates/product.liquid will be used instead of the theme’s version. You’ve successfully overridden it. The butler found your specific instructions in the room itself and stopped looking elsewhere.

The Layout Gotcha (And How to Avoid It)

Here’s the first pitfall. Look at the code above. See that {% layout 'theme' %} tag? That’s the problem. It’s explicitly telling the system to wrap this template inside the theme’s layout/theme.liquid file. This creates a dependency you probably don’t want.

What if you also need to override the layout to add a special script tag just for this page? If you create a local layout/theme.liquid, your product template is still hardcoded to use the theme’s layout, ignoring your new local one. Maddening.

The best practice is to never hardcode the layout in your overridden templates. Just remove the {% layout 'theme' %} line entirely.

{% comment %} templates/product.liquid {% endcomment %}
{% comment %} The {% layout %} tag is gone! The system will automatically find the right layout. {% endcomment %}

<div class="hero-cheese-experience">
  <h1>{{ product.title }}</h1>
  <p>Look, Ma, no hardcoded layout!</p>
</div>

Now, the system will do its precedence lookup for the layout too! It will first look for layout/product.liquid, then layout/theme.liquid in your local files, and finally fall back to the theme’s layout/theme.liquid. This gives you maximum flexibility. Want a unique layout for all products? Just create layout/product.liquid locally. It’s sublime.

Overriding Sections and Snippets

The same precedence rules apply to everything. For sections and snippets, the lookup path is even simpler:

  1. Your local file: sections/my-section.liquid or snippets/my-snippet.liquid
  2. The theme’s file: The same path within the active theme.

If you have a local sections/header.liquid file, it will completely replace the theme’s sections/header.liquid section. There’s no merging. This is a common “oh no” moment: you override a section to change one tiny thing, and you’ve accidentally deleted 20 other settings because you didn’t copy the entire original file first. Always, always start your override by pulling down the original theme file you intend to modify.

# Pull the theme's header section to your local project
theme get -t live -p sections/header.liquid
# Now you can safely edit your local copy without nuking the whole thing

This process is your guarantee against creating bizarre, broken storefronts. You’re building on a known, stable foundation rather than guessing in the dark. Now go forth and override responsibly. The cheese boards of the world are counting on you.