Skip to content

Kirby 5.1.1

    Search by Algolia

    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.

    Example

    fields:
  authors:
    label: Authors
    type: users

    Field properties

    Name Type Default Description
    $default arrayorstringorbool null Default selected user(s) when a new page/file/user is created
    $disabled bool null If true, the field is no longer editable and will not be saved
    $empty mixed null The placeholder text if none have been selected yet
    $help mixed null Optional help text below the field
    $image mixed null Image settings for each item
    $info string null Info text for each item
    $label mixed null The field label can be set as string or associative array with translations
    $layout string 'list' Changes the layout of the selected entries. Available layouts: list, cardlets, cards
    $link bool true Whether each item should be clickable
    $max int null The maximum number of allowed selected
    $min int null The minimum number of required selected
    $multiple bool true If false, only a single one can be selected
    $query string null Query for the items to be included in the picker
    $required bool null 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, huge, full
    $store string 'uuid' Whether to store UUID or ID in the content file of the model
    $text string null 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 mixed null Conditions when the field will be shown (since 3.1.0)
    $width string '1/1' The width of the field in the field grid, e.g. 1/1, 1/2, 1/3, 1/4, 2/3, 3/4

    Default values

    You can set a user email or user UUID as default value:

    fields:
  author:
    label: Author
    type: users
    default: johndoe@company.com # or user://H7jTLLW1

    Or set the default to the current user by passing true as argument:

    fields:
  author:
    label: Author
    type: users
    default: true

    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

    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 ?>