Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Kirby List Methods

List Methods is a plugin for Kirby 3 providing methods to generate comma-separated list from collections like pages, users or files. It allows for custom field selection for the list value, optional conjunctions for the last item (e. g. "and") and custom links for each item that can be defined using Kirby's query language (e. g. {{page.url}}). It also provides specific methods to list numeric values like years, shortening ranges for better readability.



Download and copy this repository to /site/plugins/list-methods.

Git submodule

git submodule add site/plugins/list-methods


composer require hananils/kirby-list-methods

Pages, Users and File Methods

There are different options to create lists from users, pages or files collections:

Comma-separated list using the primary field

Creates a list separated all items with a comma:

// using the username

// using the page title

// using the filename

Creates a list of years:

// numeric list, returns "2010–2012, 2022" for "2010, 2011, 2012, 2022"

// numeric list with "since", return "since 2020" for "2020, 2021, 2022"

Comma-separated list using a custom field or method

Creates a list separated all items with a comma:

// using the custom method `nickname`

// using the field category

// with numeric values

Comma-separated list using a conjunction

Creates a list separated all items with a comma but the last which is connected with a cunjunction:

// creates, a, list, with, commas and conjunction
$pages->toList('title', true)

// creates, a, list, with, commas & conjunction
$pages->toList('title', '&')

The default conjunction and is provided in English or German depending on your language settings.

Comma-separated list with dynamic links

Creates a list linking to a custom destination:

// link everything to the same URL
$pages->toList('title', true, '');

// link all pages to their own URL
$pages->toList('title', true, '{{page.url}}');

// link all pages to a custom URL
$pages->toList('title', true, 'my-custom-path/{{page.category}}');

// link all pages to a custom URL with numeric values
$pages->toNumericList('date', true, 'my-year-overview/{{'Y')}}');

You can use Kirby's template syntax with query language to fetch any information from the current context, e. g. the current $user, $page or $file object. The $kirby and $site objects are also available.

Content methods

When dealing with a single page or user, there are methods to generate lists from content field:

// Given the fields name and job, creates "Jane Doe, astrophysicist"
echo $user->asList(['name', 'job']);

// Given the fields start and end, creates "2020–2023"
echo $page->asNumericList(['start', 'end']);

Both methods, asList and asNumericList, support setting a custom conjunction via a secondary attribute:

//  Given the fields name and job, creates "Jane Doe: astrophysicist"
echo $page->asList(['name', 'job'], ': ');

Collection methods

The plugin also features a general, more simple collection method which is a shortcut the naturalList() helper and only allows for a custom conjunction:

// Create a Choices collection for instance, see
$choices = $page->categories()->toChoices();

// Convert all choices to a comma-separated list
echo $choices->toList();

// Convert all choices to a comma-separated list with the default conjunction
echo $choices->toList(true);

// Convert all choices to a comma-separated list with a custom conjunction
echo $choices->toList('&');


If you'd like to create a list outside of the Kirby objects, from an array for instance, you can use the naturalList() helper. It accepts a flat array and a conjunction, there is no custom key selection or template syntax support:

$data = ['this', 'that'];

// this, that

// this and that
naturalList($data, true);

// this & that
naturalList($data, '&');

If you are handling numeric values, you can use the numericList() helper:

$data = [2019, 2020, 2021, 2022];

// 2019-2022

// since 2022
numericList($data, true);


This plugin is provided freely under the MIT license by hana+nils · Büro für Gestaltung. We create visual designs for digital and analog media.


Kirby 3 plugin providing `toList()` methods for users, pages and files collections.








No packages published