Last updated Feb 17, 2022


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 WP_User ID, and can return the full WP_User data on retrieval.



  • Added return_format setting in version 5.6.9.


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

  • Select Multiple Allows multiple values to be selected. Defaults to false.

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

  • Return Format Specifies the returned value format. Defaults to ‘array’. User Array will return an array of user data. User Object will return the WP_User object. User ID will return the user ID.

For programatic documentation, please see our Register fields via PHP guide.

Template usage

Display a single selected user.

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

$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; ?>
<?php endif; ?>

Display multiple selected users.

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

$users = get_field("volunteers");
if( $users ): ?>
<ul class="volunteers-list">
    <?php foreach( $users as $user ): ?>
            <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>
    <?php endforeach; ?>
<?php endif; ?>