Skip to documentation content

Symbols

On this page

    Reserved symbols (null, true/false, empty, blank, first, last, size, etc.) and where they can be used.

    Symbols refer to an idea rather than to a specific object. Some may be used in place of an object (null, true/false) while others may only be used in a conditional (blank, empty) or as an object property. null and empty are documented on this page.

    The remaining reserved names are not types:

    true or false — The boolean values true and false. May be used anywhere a boolean is used. See also boolean under Simple Object Types.

    blank — In a conditional, tests for a null value, the boolean false, an empty string, a string containing only whitespace, or an empty list.

    key or value — Property names for the key or value of a dictionary pair. Not commonly used.

    first or last — On a list, the first or last item (null if the list is empty). If the object already has a property with that name (for example a custom field), that property wins.

    size — On a list, the number of items. If the object already has a property named size, that property wins.

    null

    An object with no value — a placeholder, like a missing chair at a table or the food on an empty plate. Written null or nil. May be used anywhere an object is used, but methods or filters that require a value can behave unexpectedly.

    Example null is falsy and invalid; empty is truthy but still invalidnull and Empty have no child properties. null (or nil) is a placeholder for a missing object and is falsy alone; empty is the empty string, which is truthy alone but still fails is_valid.
    Liquid
    {%- if null -%}
	<p>unreachable, since null is falsy alone</p>
{%- else -%}
	<p>null is falsy alone</p>
{%- endif -%}
{%- if null is_valid -%}
	<p>unreachable, since null fails is_valid</p>
{%- else -%}
	<p>null fails is_valid</p>
{%- endif -%}
{%- if empty -%}
	<p>empty is truthy alone</p>
{%- endif -%}
{%- if empty is_valid -%}
	<p>unreachable, since empty fails is_valid</p>
{%- else -%}
	<p>empty fails is_valid, even though it is truthy alone</p>
{%- endif -%}

    null (or nil) is a placeholder used where an object is missing; alone in a conditional it is falsy, and it always fails is_valid. empty is the empty string; alone in a conditional it is truthy the same as any other string, but is_valid still returns false for it. In a conditional, empty also matches an empty list, so {% if some_list == empty %} is a common way to guard an empty collection.

    empty

    The empty string (""). In a conditional, empty also matches an empty list. Used alone, empty evaluates as true; with is_valid it evaluates as false.

    Example null is falsy and invalid; empty is truthy but still invalidnull and Empty have no child properties. null (or nil) is a placeholder for a missing object and is falsy alone; empty is the empty string, which is truthy alone but still fails is_valid.
    Liquid
    {%- if null -%}
	<p>unreachable, since null is falsy alone</p>
{%- else -%}
	<p>null is falsy alone</p>
{%- endif -%}
{%- if null is_valid -%}
	<p>unreachable, since null fails is_valid</p>
{%- else -%}
	<p>null fails is_valid</p>
{%- endif -%}
{%- if empty -%}
	<p>empty is truthy alone</p>
{%- endif -%}
{%- if empty is_valid -%}
	<p>unreachable, since empty fails is_valid</p>
{%- else -%}
	<p>empty fails is_valid, even though it is truthy alone</p>
{%- endif -%}

    null (or nil) is a placeholder used where an object is missing; alone in a conditional it is falsy, and it always fails is_valid. empty is the empty string; alone in a conditional it is truthy the same as any other string, but is_valid still returns false for it. In a conditional, empty also matches an empty list, so {% if some_list == empty %} is a common way to guard an empty collection.