Users Fields

Users fields type allow you relate users to other elements.

Settings

Users fields have the following settings:

  • Sources – Which user groups (or other user index sources) the field should be able to relate users from.
  • 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.

Multi-Site Settings

On multi-site installs, the following setting will also be available (under “Advanced”):

  • Manage relations on a per-site basis – Whether each site should get its own set of related users.

The Field

Users fields list all of the currently-related 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.

Inline User Editing

When you double-click on a related user, a HUD will appear where you can edit the user’s custom fields.

Templating

If you have an element with a Users field in your template, you can access its related users using your Users field’s handle:

{% set relatedUsers = entry.<FieldHandle> %}

That will give you a user query, prepped to output all of the related users for the given field.

Examples

To loop through all of the related users, call all() and then loop over the results:

{% set relatedUsers = entry.<FieldHandle>.all() %}
{% if relatedUsers|length %}
    <ul>
        {% for rel in relatedUsers %}
            <li><a href="{{ url('profiles/'~rel.username) }}">{{ rel.name }}</a></li>
        {% endfor %}
    </ul>
{% endif %}

If you only want the first related user, call one() instead, and then make sure it returned something:

{% set rel = entry.<FieldHandle>.one() %}
{% if rel %}
    <p><a href="{{ url('profiles/'~rel.username) }}">{{ rel.name }}</a></p>
{% endif %}

If you just need to check if there are any related users (but don’t need to fetch them), you can call exists():

{% if entry.<FieldHandle>.exists() %}
    <p>There are related users!</p>
{% endif %}

You can set parameters on the user query as well. For example, to only fetch users in the authors group, set the groupId param:

{% set relatedUsers = entry.<FieldHandle>
    .group('authors')
    .all() %}

See Also