Users

The users field can be used to select one or more users. It's perfect to store authors for an article, for example.

Example

fields:
  authors:
    label: Authors
    type: users

Since 3.3.0

Up to version 3.2.5, Kirby stored users email addresses in the content file. From version 3.3.0, the user ID will be stored instead. Existing entries will be converted automatically the next time a page/file/user with a users field is saved. This should not affect your template code or email values set as defaults in your blueprints.

Field properties

Name	Type	Default	Description
default		–	Default selected user(s) when a new page/file/user is created
disabled	`bool`	–	If `true`, the field is no longer editable and will not be saved
empty		–	The placeholder text if none have been selected yet
help		–	Optional help text below the field
image		–	Image settings for each item
info	`string`	–	Info text for each item
label		–	The field label can be set as string or associative array with translations
link	`bool`	`true`	Whether each item should be clickable
max	`int`	–	The maximum number of allowed selected
min	`int`	–	The minimum number of required selected
multiple	`bool`	`true`	If `false`, only a single one can be selected
query	`string`	–	Query for the items to be included in the picker
required	`bool`	–	If `true`, the field has to be filled in correctly to be saved.
search	`bool`	`true`	Enable/disable the search field in the picker
text	`string`	–	Main text for each item
translate	`bool`	`true`	If `false`, the field will be disabled in non-default languages and cannot be translated. This is only relevant in multi-language setups.
when		–	Conditions when the field will be shown (since 3.1.0)
width	`string`	`1/1`	The width of the field in the field grid. Available widths: `1/1`, `1/2`, `1/3`, `1/4`, `2/3`, `3/4`

Default values

The default value of the user field is the current user. But you can change this default value to any existing user:

fields:
  author:
    label: Author
    type: users
    default: johndoe@company.com

Limit selection

Multiple or single mode

If you only want to select a single user, set multiple mode to false (default is true)

fields:
  author:
    label: Author
    type: users
    multiple: false

Maximum number of users

You can set the maximum number of users that can be selected:

fields:
  author:
    label: Author
    type: users
    max: 3

Query users

Since 3.2.0

You can use the query property to limit the users that can be selected:

fields:
  author:
    label: Author
    type: users
    query: kirby.users.filterBy("role", "editor")

Pagination

Since 3.3.0

Options in the pages picker are paginated. You can set the number of items per pagination page in the picker using the limit property. The default setting is 20.

fields:
  pages:
    type: pages
    label: Select an item
    limit: 10

Search

Since 3.3.0

The pages picker shows a search field by default. If you want to remove it, you can switch it off with the search option:

fields:
  pages:
    type: pages
    label: Select an item
    search: false

How to use in templates/snippets

Single user

To convert a single user to a user object, use the toUser() method:

<?php if($user = $page->author()->toUser()): ?>
  <?= $user->username() ?>
<?php endif ?>

Multiple users

To convert multiple users to a users collection, use the toUsers() method:

<?php
$users =  $page->authors()->toUsers();
foreach($users as $user): ?>
  <?= $user->username() ?>
<?php endforeach ?>