wp_dropdown_users() │ WP 2.3.0

Displays a dropdown list of users.

Uses: get_users()
1 time — 0.015165 sec (extremely slow) | 50000 times — 812.51 sec (extremely slow) | PHP 7.2.16, WP 5.2
Hooks from the function

Returns

String. Returns or displays the HTML code for the user dropdown: <select>.

Usage Template

wp_dropdown_users( array(
	'show_option_all'         => '',
	'show_option_none'        => '',
	'hide_if_only_one_author' => '',
	'orderby'                 => 'display_name',
	'order'                   => 'ASC',
	'include'                 => '',
	'exclude'                 => '',
	'multi'                   => false,
	'show'                    => 'display_name',
	'echo'                    => true,
	'selected'                => false,
	'include_selected'        => false,
	'name'                    => 'user',
	'id'                      => 'user',
	'class'                   => '',
	'blog_id'                 => $GLOBALS['blog_id'],
	'who'                     => '',
	'role'                    => '',
	'role__in'                => array(),
	'role__not_in'            => array(),
	'capability'          => '',
	'capability__in'      => array(),
	'capability__not_in'  => array(),

) );

Usage

<?php wp_dropdown_users( $args ); ?>
$args(string/array)
Array of arguments according to which the list will be formed (see below).
Default: default parameters

Arguments of the $args parameter

In addition to the parameters listed below, you can also pass parameters of the function get_users().

show_option_all(string)
Text for the "select all" list item (will be at the beginning of the list).
Default: ''
show_option_none(string)
Text for the "no user" list item (will be at the beginning of the list or second item if the show_option_all parameter is set).
Default: ''
orderby(string)

Key by which to sort the list. Can be:

  • ID - sort by user ID (theoretically in the order of registration);

  • user_nicename - sort by name;

  • display_name - sort by display name - by default.
    Default: 'display_name'
order(string)

Sorting direction:

  • ASC - in order - by default;

  • DESC - in reverse order.
    Default: 'ASC'
include(string)
User IDs to show in the list (separated by commas). For example, include=4,5,12 will output a list of three users.
Default: ''
exclude(string)
User IDs not to show in the list (separated by commas). For example, include=4,5,12 will output a list of users except the 3 specified.
Default: ''
multi(boolean)
Skip or not the ID attribute of the tag. Default 'user'.
Default: 'user'
class(string)
Value of the class attribute of the tag. Default value of the 'name' parameter.
Default: value of the 'name' parameter
blog_id(int)
Blog ID. Only for multisites. Default is the ID of the current blog.
Default: $GLOBALS['blog_id']
who(string)

Which users to display. Can be:

  • '' — show all users. (By default)
  • 'authors' — users who can publish posts (with roles: author, editor, administrator).

Default: ''

role(string/array)
Name of the user roles to include in the result. You can specify multiple names in an array. If an array is specified, the user must have all specified roles simultaneously. Since WP 4.7.
role__in(array)
Array of user role names that will be added to the result. A user will be added to the result if they have at least one of the specified roles. Since WP 4.7.
Default: array()
role__not_in(array)
Array of user role names to exclude from the result. A user will not be added to the result if they have at least one of the specified roles. Since WP 4.7.
Default: array()

Examples

0

#1 Display a drop-down list of all users

Let's turn it into a full-fledged data submission form (inside the <form> tag and with a submit button):

<h2>Users:</h2>
<form action="<?php bloginfo('url'); ?>" method="get">

   <?php wp_dropdown_users( [ 'name'=>'author' ] ); ?>

   <input type="submit" name="submit" value="view" />
</form>
0

#2 Drop-down list of authors in the posts table

See separate note.

0

#3 The who argument is no longer valid

Since version 5.9, you’ll need to use the new capabilities or role argument:

New Capability Queries in WordPress 5.9.

Changelog

Since 2.3.0 Introduced.
Since 4.5.0 Added the 'display_name_with_login' value for 'show'.
Since 4.7.0 Added the 'role', 'role__in', and 'role__not_in' parameters.
Since 5.9.0 Added the 'capability', 'capability__in', and 'capability__not_in' parameters. Deprecated the 'who' parameter.

wp_dropdown_users() code WP 6.9.1

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(),
		'capability'              => '',
		'capability__in'          => array(),
		'capability__not_in'      => array(),
	);

	$defaults['selected'] = is_author() ? get_query_var( 'author' ) : 0;

	$parsed_args = wp_parse_args( $args, $defaults );

	$query_args = wp_array_slice_assoc(
		$parsed_args,
		array(
			'blog_id',
			'include',
			'exclude',
			'orderby',
			'order',
			'who',
			'role',
			'role__in',
			'role__not_in',
			'capability',
			'capability__in',
			'capability__not_in',
		)
	);

	$fields = array( 'ID', 'user_login' );

	$show = ! empty( $parsed_args['show'] ) ? $parsed_args['show'] : 'display_name';
	if ( 'display_name_with_login' === $show ) {
		$fields[] = 'display_name';
	} else {
		$fields[] = $show;
	}

	$query_args['fields'] = $fields;

	$show_option_all   = $parsed_args['show_option_all'];
	$show_option_none  = $parsed_args['show_option_none'];
	$option_none_value = $parsed_args['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 $parsed_args The arguments passed to wp_dropdown_users() combined with the defaults.
	 */
	$query_args = apply_filters( 'wp_dropdown_users_args', $query_args, $parsed_args );

	$users = get_users( $query_args );

	$output = '';
	if ( ! empty( $users ) && ( empty( $parsed_args['hide_if_only_one_author'] ) || count( $users ) > 1 ) ) {
		$name = esc_attr( $parsed_args['name'] );
		if ( $parsed_args['multi'] && ! $parsed_args['id'] ) {
			$id = '';
		} else {
			$id = $parsed_args['id'] ? " id='" . esc_attr( $parsed_args['id'] ) . "'" : " id='$name'";
		}
		$output = "<select name='{$name}'{$id} class='" . $parsed_args['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, $parsed_args['selected'], false );
			$output   .= "\t<option value='" . esc_attr( $option_none_value ) . "'$_selected>$show_option_none</option>\n";
		}

		if ( $parsed_args['include_selected'] && ( $parsed_args['selected'] > 0 ) ) {
			$found_selected          = false;
			$parsed_args['selected'] = (int) $parsed_args['selected'];

			foreach ( (array) $users as $user ) {
				$user->ID = (int) $user->ID;
				if ( $user->ID === $parsed_args['selected'] ) {
					$found_selected = true;
				}
			}

			if ( ! $found_selected ) {
				$selected_user = get_userdata( $parsed_args['selected'] );
				if ( $selected_user ) {
					$users[] = $selected_user;
				}
			}
		}

		foreach ( (array) $users as $user ) {
			if ( 'display_name_with_login' === $show ) {
				/* translators: 1: User's 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, $parsed_args['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 ( $parsed_args['echo'] ) {
		echo $html;
	}
	return $html;
}

List (wp_list)

Other

Authors