Lists

Use lists to model repeatable content such as navigation menus, feature lists and social links. Each item shares the same structure and can be reordered directly from the editor.

Lists represent repeatable collections of values.

They allow site owners to add, remove and reorder items directly from the editor, making them ideal for navigation menus, social links, pricing tables and similar content.

Declaring a list

Lists are declared using the list type.

{
  "key": "navigation",
  "label": "Navigation",
  "type": "list",
  "item_label": "Link",
  "fields": [
    {
      "key": "title",
      "label": "Title",
      "type": "string"
    },
    {
      "key": "url",
      "label": "URL",
      "type": "url"
    }
  ]
}

Every item in the list has the same structure, defined by its child fields.

Accessing a list

Lists are available as arrays inside Liquid.

<nav>
  {% for item in theme.tokens.navigation %}
    <a href="{{ item.url }}">
      {{ item.title }}
    </a>
  {% endfor %}
</nav>

Reordering

Items can be freely reordered by the site owner.

The order defined in the editor is preserved when rendering the template.

When to use lists

Lists are useful whenever a value may occur multiple times.

Common examples include:

Navigation menus
Footer links
Social media profiles
Testimonials
Team members
Feature lists
Pricing plans

Many concepts that would traditionally become dedicated entities can instead be modelled using a simple list.

Lists and objects

Lists and objects complement each other.

Objects group related fields together.

Lists allow those grouped values to repeat.

Together they provide enough flexibility to model most structured configuration required by a theme without introducing additional concepts.