Users Fields
Users fields type allow you relate users to the parent element.
Settings #
Users fields have the following settings:
- Sources – The user groups you want to relate users from. (Default is “All”)
- Limit – The maximum number of users that can be related with the field at once. (Default is no limit.)
- Selection Label – The label that should be used on the field’s selection button.
The Field #
Users fields list all of the currently selected users, with a button to select new ones:
Clicking the “Add a user button will bring up a modal window where you can find and select additional users:
Templating #
If you have an element with a Users field in your template, you can access its selected users using your Users field’s handle:
{% set users = entry.usersFieldHandle %}
That will give you an element query, prepped to output all of the selected users for the given field. In other words, the line above is really just a shortcut for this:
{% craft.users({
relatedTo: { sourceElement: entry, field: "usersFieldHandle" },
orderBy: "sortOrder",
limit: null
}) %}
(See Relations for more info on the relatedTo param.)
Examples #
To check if your Users field has any selected users, you can use the length filter:
{% if entry.usersFieldHandle|length %}
...
{% endif %}
To loop through the selected users:
{% for user in entry.usersFieldHandle.all() %}
...
{% endfor %}
Rather than typing “entry.usersFieldHandle” every time, you can call it once and set it to another variable:
{% set users = entry.usersFieldHandle %}
{% if users|length %}
<h3>Some great users</h3>
{% for user in users %}
...
{% endfor %}
{% endif %}
You can add parameters to the ElementCriteriaModel object as well:
{% set authors = entry.usersFieldHandle.group('authors') %}
If your Users field is only meant to have a single user selected, remember that calling your Users field will still give you the same ElementCriteriaModel, not the selected user. To get the first (and only) user selected, use one():
{% set user = entry.myUsersField.one() %}
{% if user %}
...
{% endif %}