Liquid Language

Everything that can be run offline was run from a scratch folder with these commands. The first Theme Check run needs network access once to download the Liquid reference data, which it then caches.

Source: Shopify docs: Theme Check

Only nil and false are falsy. This surprises developers coming from JavaScript or PHP, because the empty string, 0 and the empty array are all truthy. The table was produced by evaluating {% if value %} in both engines, and the two agree on every row.

Because the empty string is truthy, test for content with blank: {% if product.vendor != blank %}. The keyword blank is true for nil, false, empty strings and whitespace-only strings, and for empty arrays; empty is true for empty strings, empty arrays and the empty object. The stock Ruby gem implements both keywords by calling blank? and empty? on the value, and blank? comes from Rails, so the plain gem 5.3.0 answers false for '' == blank and nil == blank, while LiquidJS and Shopify answer true. The practical rule is to rely on blank only inside a real Shopify render, and to define blank? yourself when you test with the bare gem.

Source: Shopify docs: Liquid basics, truthy and falsy

The comparison operators are ==, !=, >, <, >=, <=, and, or and contains. Comparing values of different types does not coerce them: {% if '10' == 10 %} is false in both engines, and 10 > 9 is true. Arithmetic filters do coerce strings that look like numbers: {{ '10' | plus: 5 }} prints 15, {{ '1.5' | plus: 1 }} prints 2.5, and a string with no number in it counts as 0 ({{ 'a' | plus: 'b' }} prints 0). Passing a number to append or prepend converts it to text ({{ 1 | append: 2 }} prints 12).

contains checks for a substring in a string and for an exact string element in an array of strings. It cannot find an object in an array of objects, and product.tags contains 'bea' is false because tags are compared whole.

When a tag mixes and and or, Liquid evaluates the operators from right to left and the order cannot be changed. Parentheses are not valid inside Liquid conditions: a tag that contains them fails to parse. All three results below were measured in both engines.

Source: Shopify docs: Liquid basics, order of operations

The first line is read as true and (false and (false or true)), which is false. Write conditions that need grouping as nested if tags or as separate assign steps. With parentheses the Ruby gem raises Expected dotdot but found comparison (it tries to read (1 == 1) as a range) and LiquidJS raises invalid range syntax; Theme Check reports Syntax error in 'if' tag.

Custom data reaches Liquid through metafields. Read a value with resource.metafields.<namespace>.<key>.value; the shape of the value depends on the metafield type, and it is a string for text types, a number for number types, an object for reference types (product_reference returns a product) and a date string for date and date_time, which you format with the date filter. Metafields cannot be created from Liquid. When a key is named size, first or last, use bracket notation (product.metafields.custom['size']) because dot notation can resolve to the filter of the same name. The Pocket Coffee roast date is a metafield custom.roast_date of type date, rendered by the first snippet below.

Source: Shopify docs: metafield object

assign creates a variable that lives for the rest of the file and in snippets rendered with include; it is not scoped to the block where you write it, so a value assigned inside a for loop is still there after the loop (measured: the variable holds the last item). capture stores rendered text, filters included, in a string variable. increment and decrement keep their own counters: in the measured run two {% increment a %} tags printed 0 then 1, and two {% decrement b %} tags printed -1 then -2.

Source: Shopify docs: assign tag

if, elsif, else and unless branch on the truthiness rules above; case compares one value with several when values, and a when can list alternatives separated by commas or or. Logical operators work only in conditions: you cannot write {% assign vip = a or b %} (the strict parser rejects it, see below), so compute the boolean with an if.

Source: Shopify docs: case tag

for repeats a block for each element of an array or range, accepts the parameters limit, offset and reversed, and supports an else branch that runs when the array is empty. Inside the loop the forloop object gives the position: for a three-tag array, forloop.index runs 1 to 3, forloop.index0 0 to 2, forloop.rindex 3 to 1 and forloop.rindex0 2 to 0. break leaves the loop and continue skips to the next element. cycle rotates through a list of strings inside a loop (odd and even row classes), and tablerow emits table rows and cells with cols, limit and offset parameters and a tablerowloop object.

A for loop is limited to 50 iterations per page in themes. To go through more items, wrap the array in paginate, which splits it into pages of 1 to 250 items and exposes the paginate object for the navigation links. Pagination works only up to the 25,000th item of an array, so filter a larger collection before paginating it. The arrays that can be paginated are article.comments, blog.articles, collections, collection.products, customer.addresses, customer.orders, metaobject_definition.values, pages, product.variants, search.results and the article_list, collection_list and product_list settings.

Source: Shopify docs: paginate tag

The limit parameter of for bounds the iterations but not the amount of data fetched. To fetch only what you show, put a paginate with a matching page size around the loop and keep limit as well; the documentation measures this as faster than a bare loop with limit.

Source: Shopify docs: for tag

The liquid tag removes the delimiters from a block of statements, one statement per line, and echo prints an expression inside it (equivalent to {{ }}, filters included). Long logic reads much better this way, and the lines inside a liquid tag produce no whitespace of their own. A comment inside it must be on its own line and start with #. The doc tag documents a snippet or block and is never rendered.

These tags assemble pages from other files; each has its own page of detail, so here is the summary.

Source: Shopify docs: content_for tag

A Pocket Coffee product page combines several of these: a form for the add-to-cart button, a render for each piece of reusable markup, and conditionals around the Coffee Club note. The next snippet reads the logged-in customer’s tags. customer is nil for guests, so the outer if customer protects the property access, and the result is stored in a boolean before it is used.

Source: Shopify docs: customer object

Rendered with stub filters, a Coffee Club member viewing a Beans product gets <p>Coffee Club members save 10% on beans.</p> and a guest gets an empty string. Theme Check passes the file.

The standard filters below were run with Ruby Liquid 5.3.0; the results are exactly what the engine printed.

A few behaviours deserve attention. default replaces nil, false and the empty string, but not a whitespace-only string and not 0; pass allow_false: true to keep an explicit false. divided_by returns a result of the same type as the divisor, so use a float divisor for percentages, as the free-shipping snippet below does. date accepts the strftime directives, formats date strings from metafields, and prints nothing for nil. json serializes any value for use in JavaScript and includes the quotes itself; applied to a product on a store created after 2017-12-05 it omits the variants' inventory_quantity and inventory_policy, which you read from the variant objects. Newer filters such as sum, find, find_index and has exist in Shopify and in LiquidJS 10.30.0 ({{ items | sum: 'q' }} printed 3), but the Ruby gem 5.3.0 does not know sum and echoes the array instead.

Shopify adds the filters that need store data: money formatting, CDN URLs, translations, URL helpers. None of them exist in the plain engines, so they were checked with Theme Check and are described here from the reference.

Source: Shopify docs: money filter

Because each filter receives the previous filter’s result, an expression such as {{ 'cart.free_shipping_missing' | t: amount: missing | money }} applies money to the translated sentence, not to the number. The next figure shows both versions. In the measured run with stub filters the wrong form printed €0.00 instead of the sentence, because the text is not a number (how Shopify’s own money treats a non-numeric string was not tested). The fix is to format the number into a variable and pass the variable to t.

Figure: a filter chain runs left to right on the previous result, and arguments cannot contain filters.

The first snippet prints a variant’s price, with the struck-through compare-at price when the variant is on sale. It documents its parameters with LiquidDoc, computes the sale flag in a liquid block and uses whitespace control so the markup has no stray blank lines.

Source: Shopify docs: money_with_currency filter

Rendered with stub money filters (euro sign, two decimals), a variant priced 890 cents with a compare-at price of 1090 cents gives <p class="price"><s>€10.90</s>€8.90</p>, and a 2990 cent variant with show_currency gives <p class="price">€29.90 EUR</p>. When compare_at_price is nil the comparison is false and no error is raised.

The second snippet implements the Zone 1 rule: free shipping to Spain from 40 EUR (4000 cents). It uses the math filters and the float divisor, clamps the values with at_least and at_most, and applies the lesson of the previous figure.

The two translation keys live in the locale file, where {{ amount }} is the placeholder the t filter fills:

Source: Shopify docs: translate filter

Measured with the stub filters: a cart of 31.90 EUR (3190 cents) renders <p>Add €8.10 more for free shipping to Spain</p><progress value="80" max="100"></progress>, a cart of 45.00 EUR renders <p>Free shipping to Spain unlocked</p><progress value="100" max="100"></progress>, and an empty cart renders the 40.00 EUR message with value="0". The stub that supplied money and t is short:

Source: Shopify/liquid on GitHub: the open-source engine

The stub does not reproduce Shopify’s currency formatting, translation fallbacks or pluralization, so treat these runs as checks of the Liquid logic only.

Source: Shopify docs: render tag

With for, the snippet also sees a forloop object for that implicit loop. With with and no as, the object is available under the snippet’s file name. A variable changed inside the snippet changes only the snippet’s copy. The parameters of render accept values, not expressions: Shopify’s strict parser rejects filters, comparison operators or a bare variable name among the arguments (see the strict parsing section for the exact rewrites).

Replace each include with render in three steps. First list the variables the snippet reads from its caller; Theme Check helps because a snippet documented with LiquidDoc reports the parameters it expects. Second, pass those variables as named arguments. Third, if the snippet used to assign a variable for the caller, return the value another way: compute it in the caller, move the assignment into the caller, or render the snippet into a variable with capture.

Source: Shopify docs: include tag

Measured with Ruby Liquid 5.3.0 in strict mode. Theme Check reports the same defects through the LiquidHTMLSyntaxError or LiquidSyntaxError checks with its own, shorter wording.

Source: Liquid documentation

The next file collects the mistakes that Theme Check can find. It was added to the Skeleton copy and checked; the output follows (line numbers are one-based and omitted here).

Source: Shopify docs: Theme Check checks

undefined_thing was not reported in that snippet because Theme Check does not know which objects a snippet receives; in a template the same mistake is caught. Adding {{ produt.title }} to the product template produced the warning UndefinedObject, Unknown object 'produt' used. Other defects found in separate files: an unclosed if gave the error LiquidHTMLSyntaxError Attempting to end parsing before LiquidTag 'if' was closed; a trailing pipe gave Syntax is not supported. Remove the trailing | character.; an unclosed {{ gave Expected LiquidVariableOutputClose but got EndOfInput; an HTML element opened inside an if and never closed gave the warning UnclosedHTMLElement; and parentheses in a condition gave Syntax error in 'if' tag. A stray closing div left in a collection template after an edit is caught the same way: Attempting to close HtmlElement 'div' before it was opened.

The CLI exits with a non-zero code only for errors by default, which suits CI. Use --fail-level warning to fail on warnings, -a to apply the automatic fixes, -C theme-check:all to enable every check and --init to write a .theme-check.yml. The checks with thresholds are LiquidComplexity (a warning above 120) and ExcessiveSettingsCount (above 40 settings).

Source: Shopify docs: Theme Check checks

Source: Shopify docs: Liquid basics

The Prettier plugin @shopify/prettier-plugin-liquid (1.11.3) formats Liquid with the parser liquid-html, and @shopify/liquid-html-parser (2.11.0) exposes the syntax tree; an unclosed tag throws while parsing. Running the plugin on untidy input produced this result:

Source: Shopify/theme-tools: Theme Check, Prettier plugin and language server