Users
A user select field that allows to select one or multiple users
The users field can be used to select one or more users. It's perfect to store authors for an article, for example.
![](https://v39.getkirby.com/media/pages/docs/reference/panel/fields/users/715a7d1b53-1704284774/users-960x.png)
Example
fields:
authors:
label: Authors
type: users
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 | |
layout | string |
list |
Changes the layout of the selected entries. |
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 |
size | string |
auto |
Layout size for cards: tiny , small , medium , large or huge
|
store | string |
uuid |
Whether to store UUID or ID in the content file of the model |
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
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
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
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 ?>