User

Last updated Feb 5, 2024

Description

The User field allows the selection of one or more users.

This field type is useful for creating relationships between data objects. It stores its value as the WordPress user ID, and can return the full WP_User data on retrieval.

Screenshots

Creating a User field in an ACF field group. The tab shown depicts General settings for the field: Field Type, Field Label, Field Name, Filter by Role, Return Format (a radio button with choices of User Array, User Object, and User ID), and Select Multiple.The other tabs are Validation, Presentation, Conditional Logic, and Advanced.

Creating a User field in an ACF field group.

The User field UI as it might appear to content editors, with users sorted by role. The Editor and Contributor roles are showing here, with two entries in each.

The User field UI as it might appear to content editors, with users sorted by role.

Changelog

  • Added return_format setting in version 5.6.9.

Settings

  • Filter by Role
    Filters the available users by one or more user roles. Defaults to an empty string.

  • Return Format
    Specifies the returned value format. Defaults to “User Array” in the plugin’s UI, and ‘array’ in PHP. “User Array” returns an array of user data, “User Object” returns the WP_User object, and “User ID” returns the user ID.

  • Select Multiple
    Allows content editors to select multiple values. Defaults to off.

  • Required
    Enabling this prevents the field from accepting empty values. Defaults to off.

  • Allow Null
    Allows an empty value to be saved. Defaults to off.

  • Instructions
    Shows instructions when submitting data.

  • Conditional Logic
    Enabling this setting allows you to customize the logic which determines if the current field should be visible. Groups of conditional logic rules can be created to allow for multiple and/or statements.

  • Bidirectional
    Found on the Advanced tab, enabling this setting allows you to update a value in the target fields for each value selected for this field, adding or removing the Post ID, Taxonomy ID, or User ID of the item being updated.

For programmatic documentation, please see our guide to registering fields via PHP.

Template usage

Display a single selected user

This example demonstrates how to display a selected user (‘multiple’ = false, return_format = ‘array’).

<?php
$user = get_field("user_field");
if( $user ): ?>
<div class="author-box">
    <img src="<?php echo esc_attr($user['user_avatar']); ?>" alt="author-avatar" />
    <h3><?php echo $user['display_name']; ?></h3>
    <?php if( $user['user_description'] ): ?>
        <p><?php echo $user['user_description']; ?></p>
    <?php endif; ?>
</div>
<?php endif; ?>

Display multiple selected users

This example demonstrates how to display multiple selected users in a list. (‘multiple’ = true, return_format = ‘object’).

<?php
$users = get_field("volunteers");
if( $users ): ?>
<ul class="volunteers-list">
    <?php foreach( $users as $user ): ?>
        <li>
            <img src="<?php echo esc_attr( get_avatar($user->ID) ); ?>" alt="author-avatar" />
            <a href="<?php echo esc_attr($user->user_url); ?>"><?php echo $user->display_name; ?></a>
        </li>
    <?php endforeach; ?>
</ul>
<?php endif; ?>