Users Fields

This document is for a version of Craft CMS that is no longer supported. Please refer to the latest version →

Users fields type allow you relate users to the parent element.

# Settings

users-settings.2x

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:

users-entry.2x

Clicking the “Add a user button will bring up a modal window where you can find and select additional users:

users-entry-add.2x

# 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 ElementCriteriaModel object, 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" },
  order:     "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, you can treat the field like an array:

{% for user in entry.usersFieldHandle %}
  ...
{% 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 first():

{% set user = entry.myUsersField.first() %}

{% if user %}
  ...
{% endif %}

# See Also