Dictionary Tag

This tag allows you to loop through options from a Dictionary.

{{ dictionary handle="countries" }}
    {{ label }} {{ value }}
{{ /dictionary }}

You can also use the shorthand syntax for this:

{{ dictionary:countries }}
    {{ label }} {{ value }}
{{ /dictionary:countries }}

You can also output any additional data provided by the Dictionary, like emoji or region in the case of the Countries dictionary:

{{ dictionary:countries }}
    {{ emoji }} {{ name }} in {{ region }}
{{ /dictionary:countries }}

Searching

{{ dictionary:countries search="Aus" }}
    {{ label }} {{ value }}
{{ /dictionary:countries }}

🇦🇺 Australia AUS
🇦🇹 Austria AUT

Conditions

{{ dictionary:countries region:is="Europe" }}
    {{ label }} {{ value }}
{{ /dictionary:countries }}

There are a bunch of conditions available to you, like :is, :isnt, :contains, :starts_with, and :is_before. There are many more than that. In fact, there's a whole page dedicated to conditions - check them out.

Paginating

To enable pagination mode, add the paginate parameter with the number of options in each page.

{{ dictionary:countries paginate="10" as="countries" }}
    {{ countries }}
        {{ label }}<br>
    {{ /countries }}
 
    {{ paginate }}
        <a href="{{ prev_page }}">⬅ Previous</a>
 
        {{ current_page }} of {{ total_pages }} pages
        (There are {{ total_items }} posts)
 
        <a href="{{ next_page }}">Next ➡</a>
    {{ /paginate }}
{{ /dictionary:countries }}

In pagination mode, your options will be scoped (in the example, we're scoping them into the countries tag pair). Use that tag pair to loop over the options in that page.

The paginate variable will become available to you. This is an array containing data about the paginated set.

Query Scopes

Doing something custom or complicated? You can create query scopes to narrow down those results with the query_scope or filter parameter:

{{ dictionary:countries query_scope="your_query_scope" }}

You should reference the query scope by its handle, which is usually the name of the class in snake case. For example: YourQueryScope would be your_query_scope.

Files

One of the powerful things you can do with the Files dictionary is pull in options from a JSON, YAML or CSV file.

{{ dictionary:file filename="products.json" label="Name" value="Code" paginate="5" }}

Parameters