Users fields type allow you relate users to other elements.

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.

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.

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.

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

When querying for elements that have a Users field, you can filter the results based on the Users field data using a query param named after your field’s handle.

Possible values include:

{# Fetch entries with a related user #}
{% set entries = craft.entries()
    .<FieldHandle>(':notempty:')
    .all() %}

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 query = entry.<FieldHandle> %}

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

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 = clone(entry.<FieldHandle>)
    .group('authors')
    .all() %}

::: tip It’s always a good idea to clone the user query using the clone() function before adjusting its parameters, so the parameters don’t have unexpected consequences later on in your template. :::

• User Queries
• api:craft\elements\User
• Relations