New - Liquid Tag Reference
On this page
The new tag creates a value and assigns it to a variable: an empty or JSON-seeded List or Map, a UUID, or a random number. Use it to start a collection that you then build up with filters.
Syntax
```liquid
{% new
| Property | Value |
|---|---|
| Tag Name | new |
| Type | Simple tag |
| Source | Hydrofoil (core) |
Types
| Type | Creates | Seed or options | Available in POS |
|---|---|---|---|
List |
A list | Optional JSON array string, such as '["a","b"]' |
Yes |
Map |
A map of keys to values | Optional JSON object string, such as '{"mode":"grid"}' |
Yes |
UUID |
A random version 4 UUID string | None | No |
Rand |
A random number between min and max, inclusive |
min (default 0) and max (default 100) |
No |
The type name is case-sensitive. Any other type name stops the template with Liquid syntax error (line N): unknown object type <name>.
Empty and seeded lists and maps
Leave off the = and the value to create an empty List or Map. This is the usual way to start a collection:
```liquid
{%- new List codes -%} {%- new Map labels -%} ```
To start with values, pass a JSON string after =. The value is parsed as JSON each time the tag renders:
```liquid
{%- new List codes = ‘[“red”,”green”]’ -%} {%- new Map settings = ‘{“mode”:”grid”,”columns”:3}’ -%} {{ settings.mode }} ```
On the web storefront, the seed must be a JSON string. Each of these gives an empty List or Map instead, with no error on the page:
- An empty string, such as
{% new Map settings = '' %}. - Text that is not valid JSON. A typo in the seed therefore looks like missing data.
- A value that is not a string, such as the list from
{% new List parts = 'a,b' | split: ',' %}. To keep a list you already have,assignit instead.
:::note POS views differ on the last point: on the POS, a seed that is already a List or Map is copied into the new variable rather than discarded. :::
Inside loops
The tag creates a fresh List or Map every time it renders. Placed inside a {% for %} loop, it resets the variable on each pass, which suits a per-item collection. To collect values across every pass, create the List or Map before the loop.
Building up a list or map
Add to a Map with the set_key filter and to a List with the push filter. Assign the result back to the variable. A Map read from the variable is a fresh copy each time, so a set_key that is not assigned back is lost.
```liquid
{%- new Map names_by_code -%} {%- for product in content_block.products -%} {%- assign names_by_code = names_by_code | set_key: product.product_code, product.name -%} {%- endfor -%}
{{ names_by_code | json }} ```
In a featured products block holding two products coded TEE-01 and CAP-02, this outputs {"TEE-01":"Classic tee","CAP-02":"Canvas cap"}.
UUID and random numbers
```liquid
{%- new UUID request_ref -%} {%- new Rand dice min: 1, max: 6 -%}
Reference {{ request_ref }}: you rolled {{ dice }}.
```
request_ref holds a value such as 550e8400-e29b-41d4-a716-446655440000, and dice holds a whole number from 1 to 6. Both change on every render. Inside a {% cache %} block, the cached output keeps the first value until the block expires.
Was this article helpful?
Thanks for your feedback! It helps us improve our docs.