Skip to content
Tutorials Center
My learning

Topics

Lesson 40 of 61 ยท Performance and Quality

Liquid Performance: Loops, Objects and Limits

Write faster Liquid: avoid nested loops and heavy filters, respect paginate limits, choose render over include, and find slow sections with the theme profiler.

Liquid runs on Shopify's servers before the HTML is sent, so slow Liquid delays the very first byte of every page. A visitor never sees your loops, but they feel them as a longer wait before anything appears. Shopify caches a lot and keeps Liquid fast for typical themes, yet a section that loops over hundreds of items inside another loop can still add real time to every request.

This lesson is about the cost model of Liquid: what is cheap, what is expensive, and what the platform limits. You will learn to spot the patterns that scale badly, and to measure instead of guessing. The theme code is read-only (it only runs on Shopify). The runnable TryIt blocks are stand-ins: a tiny cost counter written in JavaScript that shows how operation counts grow, which is the same reasoning you apply to real Liquid.

Shopify does not publish an exact time budget per Liquid operation, and limits such as the number of items an array can return have changed over the years. Treat the numbers in this lesson as principles, and check the current Liquid reference for hard limits before you rely on one.

What makes Liquid slow

Almost every slow template falls into one of these groups:

  • Nested loops that multiply work: 50 products times 100 variants times 10 metafields.
  • Repeated work inside a loop that could be done once outside it.
  • Reading many objects you do not display (each access to something like a metafield or a collection of products costs lookups).
  • Heavy filters on big arrays (sort, where, map over thousands of items) executed many times.
  • Rendering far more than the shopper sees, such as printing 250 hidden items.

None of these is a bug. They are just choices that cost more as the catalog grows. A theme that is fine for a 20-product demo store can be slow for a store with 20,000 products.

flowchart TD
  A["Request arrives"] --> B["Shopify loads objects"]
  B --> C["Liquid runs: tags, loops, filters"]
  C --> D["HTML is built"]
  D --> E["Response sent"]
  C -. "More loop iterations = longer C" .-> C

Everything between the request and the response is on the critical path, so Liquid time is added to every uncached visit.

Loops and how they multiply

A loop costs roughly the number of iterations times the work inside. A nested loop costs the product of both sizes:

LIQUID
{%- for product in collection.products -%}
  {%- for variant in product.variants -%}
    {%- for option in product.options_with_values -%}
      ...
    {%- endfor -%}
  {%- endfor -%}
{%- endfor -%}

With 50 products, 20 variants each and 3 options, the innermost line runs 3,000 times. Ask for each loop whether it is needed. Often the answer is no:

  • To show a "from" price, use product.price_min instead of looping through variants to find the lowest one.
  • To check whether any variant is available, use product.available instead of looping and testing each one.
  • To show option names, read product.options rather than collecting them in a nested loop.

Use limit to stop early, and break when you have found what you need (see Loops):

LIQUID
{%- for block in section.blocks limit: 6 -%}
  {% render 'promo-tile', block: block %}
{%- endfor -%}

Pagination and the limits that matter

When you loop over a collection's products, you never get the whole catalog. The paginate tag splits a long array into pages, and collection.products is limited to a bounded page size. This is a feature, not a problem: a page that renders 24 cards is faster than one that renders 2,000.

LIQUID
{%- paginate collection.products by 24 -%}
  {%- for product in collection.products -%}
    {% render 'product-card', product: product %}
  {%- endfor -%}
  {{ paginate | default_pagination }}
{%- endpaginate -%}

Practical rules:

  • Pick a page size that fills the screen without excess. Twelve to forty-eight cards is typical.
  • Keep the loop inside paginate, and loop over the paginated array only.
  • The maximum page size is bounded by the platform (check the current reference), so do not design a page that assumes "all products".
  • Some objects, such as an unpaginated product's variants, are also bounded. If a product can have very many variants, never assume your loop sees all of them; the option picker logic in Variants and Option Pickers works with the data the object provides.

For filtering and sorting large sets, let Shopify do it. Storefront filtering and sort_by are computed before your loop runs, which is far cheaper than sorting inside Liquid (see Collection Pages).

Filters: cheap and expensive

Most filters on a single string or number are very cheap: upcase, plus, money. The ones to watch are those that walk an array:

Filter Cost grows with Tip
where, map, sort, uniq array length Run once, store the result with assign, reuse it
size on a built-in array nothing much Fine to call
split on a very long string string length Avoid in loops
image_url / image_tag number of images Fine; keep the count sensible

The cost of repeating a computation is the real danger. This looks harmless:

LIQUID
{%- for product in collection.products -%}
  {%- assign sale_tags = shop.metafields.custom.sale_tags.value | where: 'active', true -%}
  ...
{%- endfor -%}

The where result does not depend on product, so it runs once per product for no reason. Move it above the loop. This pattern, called hoisting, is the most common Liquid optimization.

render versus include

include is deprecated. render is the tag to use, and it is better for performance as well as design: a snippet rendered with render gets its own isolated scope, so Shopify does not have to expose and track the parent's variables (see Snippets and the render Tag). Two habits keep snippets cheap:

  • Render snippets with only the variables they need, rather than passing a huge object and reading ten properties from it.
  • Do not wrap a tiny amount of markup in a snippet that you call hundreds of times in a loop, when a plain expression would do. A snippet call has overhead, so a 50-card grid is fine, but a snippet for every <span> is not.

Do less on the server

Sometimes the fastest Liquid is none at all:

  • Lazy sections. Content below the fold, such as a long reviews list or a recommendations block, can be fetched after load with the Section Rendering API. The first response then stays small.
  • Product recommendations. Load them with a request after the page appears instead of computing them during the main render.
  • Fewer sections per page. A home page with 25 sections costs more than one with 8, even if each is simple.
  • Hidden content. Do not render a hidden mobile and desktop copy of a heavy block; use one block and CSS.

Page caching at Shopify's edge also helps, but personalized output (a logged-in customer, a cart) cannot be shared between visitors, so assume the Liquid runs.

Measuring instead of guessing

Opinions about "slow" code are often wrong. Measure:

  1. Shopify Theme Inspector for Chrome produces a flame graph of Liquid render time, showing which sections, snippets and tags took the longest on a real page.
  2. The Shopify CLI includes profiling support for themes; check shopify theme --help for the profiling command available in your CLI version.
  3. Theme Check (see Theme Check, Linting and Testing) flags some known costly patterns before you publish.
Terminal
# Run Theme Check on the current theme folder
shopify theme check

Profile a page with realistic data: a development store with five products hides every problem in this lesson.

Stand-in: count operations

A real profiler reports time. This stand-in reports operation counts, which is the part you control. It simulates three versions of the same task, finding the cheapest variant price for every product, and counts how many times the inner work runs.

JS Stand-in: nested loop versus built-in lookup

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Both versions give the same prices, but the nested loop does as many operations as there are variants, while the built-in lookup does one per product. Real Liquid is not measured in operations alone, yet the growth pattern is the lesson: one loop level is the difference between 48 and 4,800.

Stand-in: hoisting repeated work

The second stand-in wraps a filter in a counter so you can see how often it runs. The filter result never changes inside the loop, so computing it once is both faster and easier to read.

JS Stand-in: move a loop-invariant filter outside the loop

Press Run (or Ctrl + Enter) to see the console output here.

No output.

In Liquid the equivalent change is moving {% assign active_promos = ... | where: 'active', true %} above the for tag. The saving here is 40 times fewer items examined, and it grows with every product you add to the page.

A Liquid performance checklist

  • Prefer built-in properties (price_min, available, featured_image) over loops that recompute them.
  • Hoist anything that does not depend on the loop variable.
  • Paginate, use limit, and break early.
  • Use render with narrow arguments.
  • Lazy-load below-the-fold sections.
  • Profile with real catalog data, then fix the largest cost first.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. A section loops over 40 products and, inside each, over 30 variants to find the lowest price. What is the best fix?

    price_min is precomputed, so it removes the inner loop entirely and does the same job in one lookup.
  2. 2. What does hoisting mean in Liquid?

    A filter whose result is the same on every iteration should run once, outside the loop, and be stored with assign.
  3. 3. Why is paginate good for performance?

    Rendering a page of cards instead of the whole catalog keeps the loop short and the response small.
  4. 4. Which tool shows where Liquid render time is spent on a real page?

    A profiler produces a flame graph of sections, snippets and tags, so you fix the biggest cost instead of guessing.
  5. 5. Which is the preferred tag for reusing a snippet?

    render is current, isolates scope and is the recommended tag; include is deprecated.

Summary

  • Liquid time is added to every uncached request, so loops and filters matter.
  • Nested loops multiply cost; replace them with built-in properties wherever possible.
  • Hoist loop-invariant filters, and store results with assign.
  • Paginate, limit and break to bound the work, and remember that platform limits exist.
  • Use render with narrow arguments, and lazy-load heavy content below the fold.
  • Measure with a profiler on realistic data before and after each change.

Next, make the theme usable for everyone in Accessibility in Themes.