User

Documentation Field Types 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

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; ?>