Choices offers methods to resolve selections stored by select, multiselect or checkboxes fields back to their human-readable values. It also gives access to the full list of options defined in the blueprint, either written statically or loaded via query or api settings.
Choices’ primary usecase is outputting selections and field options on the frontend. For instance, you can use it to show categories and tags or to create classes and data attributes from a selection. It can also be used to resolve selections in info or help texts inside of panel sections.
Choices is used as shared term for both selection and option lists.
The plugin creates a collection of all choices and allows you to evaluate, manipulate and convert them on the fly.
- all: bool
Whether to include all defined choices or not. Defaults tofalse. - context: string
The name of the parent, if the field is nested. Defaults tonull.
Given a field with options, this class retrieves all choices made by the editors or – if the all parameter is set – of all options defined for this field.
In case of nested fields, e. g. when used inside a structure field, the name of the parent field must be passed as context in order to retrieve the choices.
Choices extends the default Kirby Collection class and thus offers all methods known from other Kirby object like first(), last(), shuffle(), sort() and the like.
Given a select field with fruits, either return the selected or all available options in human readable format.
fields:
fruits:
label: Fruits
type: select
options:
apple: Apple
pear: Pear
banana: BananaTitle: Choices example
-----
Fruits: apple, pear// Return selected fruits: "Apple Pear"
<?php foreach ($page->fruits()->toChoices() as $fruit): ?>
<?= $fruit ?>
<?php endforeach; ?>// Return all fruit options: "Apple Pear Banana"
<?php foreach ($page->fruits()->toChoices(all: true) as $fruit): ?>
<?= $fruit ?>
<?php endforeach; ?>// Return selected fruits: "Apple, Pear"
<?= $pages->fruits()->toChoices()->join() ?>Tip
See the manipulation guides to learn how to use Kirby’s string methods on all choices before output. There are also methods to evaluate the existence or non-existence of a choice and further options to convert content to another type – for instance, switching between text and value output.
By default, plugins in Kirby reside in a special folder located at /site/plugins. Each plugin is installed in its proprietary subfolder. This installation can be handled in four different ways: you can either install them manually or manage them using Kirby CLI, Git submodules or Composer. You can install Choices either way and should choose the method suiting your project best.
Please note that all examples given here assume you are using the default plugin root. If you changed your plugin root, e. g. with a custom folder setup, you’ll also have to adjust the paths given in this guide. For further information on how to manage plugins, please read the official Kirby plugin introduction.
Download and copy this repository to /site/plugins/choices.
kirby plugin:install hananils/kirby-choicesgit submodule add \
https://github.com/hananils/kirby-choices.git \
site/plugins/choicescomposer require hananils/kirby-choicesWhere possible, files contain inline annotations. For extended documentation, please visit our dedicated plugin site at kirby.hananils.de/plugins/choices.
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.

