wp_dropdown_users

Create dropdown HTML content of users.

Description

(string) wp_dropdown_users( (string) $args = '' );

The content can either be displayed, which it is by default or retrieved by setting the echo argument. The include, and exclude arguments do not need to be used; all users will be displayed in that case. Only one can be used, either include, or exclude, but not both.

The available arguments are as follows:

Returns (string)

String of HTML content.

Parameters (1)

0. $args — Optional. (string) => ''

Array or string of arguments to generate a drop-down of users. See WP_User_Query::prepare_query(…) for additional available arguments.

show_option_all (string) => ''
Text to show as the drop-down default (all).
show_option_none (string) => ''
Text to show as the drop-down default when no users were found.
option_none_value (int|string) => -1
Value to use for $show_option_non when no users were found.
hide_if_only_one_author (string) => ''
Whether to skip generating the drop-down if only one user was found.
orderby (string) => 'display_name'
Field to order found users by. Accepts user fields.
order (string) => 'ASC'
Whether to order users in ascending or descending order. Accepts ASC (ascending) or DESC (descending).
include (array|string) => ''
Array or comma-separated list of user IDs to include.
exclude (array|string) => ''
Array or comma-separated list of user IDs to exclude.
multi (bool|int) => 0
Whether to skip the ID attribute on the select element. Accepts 1|true or 0|false.
show (string) => 'display_name'
User data to display. If the selected item is empty then the user_login will be displayed in parentheses. Accepts any user field, or display_name_with_login to show the display name with user_login in parentheses.
echo (int|bool) => 1
Whether to echo or return the drop-down. Accepts 1|true (echo) or 0|false (return).
selected (int) => 0
Which user ID should be selected.
include_selected (bool) => false
Whether to always include the selected user ID in the drop- down.
name (string) => 'user'
Name attribute of select element.
id (string) => is the value of $name
ID attribute of the select element.
class (string) => ''
Class attribute of the select element.
blog_id (int) => is ID of the current blog
ID of blog (Multisite only).
who (string) => ''
Which type of users to query. Accepts only an empty string or authors..
role (string|array) => ''
An array or a comma-separated list of role names that users must match to be included in results. Note that this is an inclusive list: users must match *each* role.
role__in (array) => array()
An array of role names. Matched users must have at least one of these roles.

array(

    /**
     * Text to show as the drop-down default (all).
     *
     * @type string
     * @default ''
     */
    'show_option_all' => '',

    /**
     * Text to show as the drop-down default when no users were found.
     *
     * @type string
     * @default ''
     */
    'show_option_none' => '',

    /**
     * Value to use for $show_option_non when no users were found.
     *
     * @type int|string
     * @default -1
     */
    'option_none_value' => -1,

    /**
     * Whether to skip generating the drop-down if only one user was found.
     *
     * @type string
     * @default ''
     */
    'hide_if_only_one_author' => '',

    /**
     * Field to order found users by. Accepts user fields.
     *
     * @type string
     * @default 'display_name'
     */
    'orderby' => 'display_name',

    /**
     * Whether to order users in ascending or descending order. Accepts 'ASC' (ascending) or 'DESC'
     * (descending).
     *
     * @type string
     * @default 'ASC'
     */
    'order' => 'ASC',

    /**
     * Array or comma-separated list of user IDs to include.
     *
     * @type array|string
     * @default ''
     */
    'include' => '',

    /**
     * Array or comma-separated list of user IDs to exclude.
     *
     * @type array|string
     * @default ''
     */
    'exclude' => '',

    /**
     * Whether to skip the ID attribute on the 'select' element. Accepts 1|true or 0|false.
     *
     * @type bool|int
     */
    'multi' => 0,

    /**
     * User data to display. If the selected item is empty then the 'user_login' will be displayed in
     * parentheses. Accepts any user field, or 'display_name_with_login' to show the display name
     * with user_login in parentheses.
     *
     * @type string
     * @default 'display_name'
     */
    'show' => 'display_name',

    /**
     * Whether to echo or return the drop-down. Accepts 1|true (echo) or 0|false (return).
     *
     * @type int|bool
     * @default 1
     */
    'echo' => 1,

    /**
     * Which user ID should be selected.
     *
     * @type int
     */
    'selected' => 0,

    /**
     * Whether to always include the selected user ID in the drop- down.
     *
     * @type bool
     * @default false
     */
    'include_selected' => false,

    /**
     * Name attribute of select element.
     *
     * @type string
     * @default 'user'
     */
    'name' => 'user',

    /**
     * ID attribute of the select element.
     *
     * @type string
     * @default is the value of $name
     */
    'id' => is the value of $name,

    /**
     * Class attribute of the select element.
     *
     * @type string
     * @default ''
     */
    'class' => '',

    /**
     * ID of blog (Multisite only).
     *
     * @type int
     * @default is ID of the current blog
     */
    'blog_id' => is ID of the current blog,

    /**
     * Which type of users to query. Accepts only an empty string or 'authors'.
     *
     * @type string
     * @default ''
     */
    'who' => '',

    /**
     * An array or a comma-separated list of role names that users must match to be included in
     * results. Note that this is an inclusive list: users must match *each* role.
     *
     * @type string|array
     * @default ''
     */
    'role' => '',

    /**
     * An array of role names. Matched users must have at least one of these roles.
     *
     * @type array
     * @default array()
     */
    'role__in' => array()
);

…

Usage

if ( !function_exists( 'wp_dropdown_users' ) ) { 
    require_once ABSPATH . WPINC . '/user.php'; 
} 
  
// Optional. Array or string of arguments to generate a drop-down of users. See WP_User_Query::prepare_query() for additional available arguments. 
$args = array( 
    'show_option_all' => '', 
    'show_option_none' => '', 
    'option_none_value' => -1, 
    'hide_if_only_one_author' => '', 
    'orderby' => 'display_name', 
    'order' => 'ASC', 
    'include' => '', 
    'exclude' => '', 
    'multi' => 0, 
    'show' => 'display_name', 
    'echo' => 1, 
    'selected' => 0, 
    'include_selected' => false, 
    'name' => 'user', 
    'id' => is the value of $name, 
    'class' => '', 
    'blog_id' => is ID of the current blog, 
    'who' => '', 
    'role' => '', 
    'role__in' => array() 
); 
  
// NOTICE! Understand what this does before running. 
$result = wp_dropdown_users($args);

Defined (1)

The function is defined in the following location(s).

/wp-includes/user.php

function wp_dropdown_users( $args = '' ) { 
    $defaults = array( 
        'show_option_all' => '', 'show_option_none' => '', 'hide_if_only_one_author' => '',  
        'orderby' => 'display_name', 'order' => 'ASC',  
        'include' => '', 'exclude' => '', 'multi' => 0,  
        'show' => 'display_name', 'echo' => 1,  
        'selected' => 0, 'name' => 'user', 'class' => '', 'id' => '',  
        'blog_id' => get_current_blog_id(), 'who' => '', 'include_selected' => false,  
        'option_none_value' => -1,  
        'role' => '',  
        'role__in' => array(),  
        'role__not_in' => array(),  
 ); 
 
    $defaults['selected'] = is_author() ? get_query_var( 'author' ) : 0; 
 
    $r = wp_parse_args( $args, $defaults ); 
 
    $query_args = wp_array_slice_assoc( $r, array( 'blog_id', 'include', 'exclude', 'orderby', 'order', 'who', 'role', 'role__in', 'role__not_in' ) ); 
 
    $fields = array( 'ID', 'user_login' ); 
 
    $show = ! empty( $r['show'] ) ? $r['show'] : 'display_name'; 
    if ( 'display_name_with_login' === $show ) { 
        $fields[] = 'display_name'; 
    } else { 
        $fields[] = $show; 
    } 
 
    $query_args['fields'] = $fields; 
 
    $show_option_all = $r['show_option_all']; 
    $show_option_none = $r['show_option_none']; 
    $option_none_value = $r['option_none_value']; 
 
    /** 
     * Filters the query arguments for the list of users in the dropdown. 
     * 
     * @since 4.4.0 
     * 
     * @param array $query_args The query arguments for get_users(). 
     * @param array $r          The arguments passed to wp_dropdown_users() combined with the defaults. 
     */ 
    $query_args = apply_filters( 'wp_dropdown_users_args', $query_args, $r ); 
 
    $users = get_users( $query_args ); 
 
    $output = ''; 
    if ( ! empty( $users ) && ( empty( $r['hide_if_only_one_author'] ) || count( $users ) > 1 ) ) { 
        $name = esc_attr( $r['name'] ); 
        if ( $r['multi'] && ! $r['id'] ) { 
            $id = ''; 
        } else { 
            $id = $r['id'] ? " id='" . esc_attr( $r['id'] ) . "'" : " id='$name'"; 
        } 
        $output = "<select name='{$name}'{$id} class='" . $r['class'] . "'>\n"; 
 
        if ( $show_option_all ) { 
            $output .= "\t<option value='0'>$show_option_all</option>\n"; 
        } 
 
        if ( $show_option_none ) { 
            $_selected = selected( $option_none_value, $r['selected'], false ); 
            $output .= "\t<option value='" . esc_attr( $option_none_value ) . "'$_selected>$show_option_none</option>\n"; 
        } 
 
        if ( $r['include_selected'] && ( $r['selected'] > 0 ) ) { 
            $found_selected = false; 
            $r['selected'] = (int) $r['selected']; 
            foreach ( (array) $users as $user ) { 
                $user->ID = (int) $user->ID; 
                if ( $user->ID === $r['selected'] ) { 
                    $found_selected = true; 
                } 
            } 
 
            if ( ! $found_selected ) { 
                $users[] = get_userdata( $r['selected'] ); 
            } 
        } 
 
        foreach ( (array) $users as $user ) { 
            if ( 'display_name_with_login' === $show ) { 
                /** translators: 1: display name, 2: user_login */ 
                $display = sprintf( _x( '%1$s (%2$s)', 'user dropdown' ), $user->display_name, $user->user_login ); 
            } elseif ( ! empty( $user->$show ) ) { 
                $display = $user->$show; 
            } else { 
                $display = '(' . $user->user_login . ')'; 
            } 
 
            $_selected = selected( $user->ID, $r['selected'], false ); 
            $output .= "\t<option value='$user->ID'$_selected>" . esc_html( $display ) . "</option>\n"; 
        } 
 
        $output .= "</select>"; 
    } 
 
    /** 
     * Filters the wp_dropdown_users() HTML output. 
     * 
     * @since 2.3.0 
     * 
     * @param string $output HTML output generated by wp_dropdown_users(). 
     */ 
    $html = apply_filters( 'wp_dropdown_users', $output ); 
 
    if ( $r['echo'] ) { 
        echo $html; 
    } 
    return $html; 
}