wp_dropdown_users( array|string $args = '' ): string

Description

Parameters

$argsarray|stringoptional

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

• $show_option_allstringdefault: empty

  Text to show as the drop-down default (all).

• $show_option_nonestringdefault: empty

  Text to show as the drop-down default when no users were found.

• $option_none_valueint|stringdefault: -1

  Value to use for $show_option_none when no users were found.

• $hide_if_only_one_authorstringdefault: empty

  Whether to skip generating the drop-down if only one user was found.

• $orderbystringdefault: 'display_name'

  Field to order found users by. Accepts user fields.

• $orderstringdefault: 'ASC'

  Whether to order users in ascending or descending order. Accepts 'ASC' (ascending) or 'DESC' (descending).

• $includeint[]|stringdefault: empty

  Array or comma-separated list of user IDs to include.

• $excludeint[]|stringdefault: empty

  Array or comma-separated list of user IDs to exclude.

• $multibool|intdefault: 0|false

  Whether to skip the ID attribute on the 'select' element. Accepts 1|true or 0|false.

• $showstringdefault: '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.

• $echoint|booldefault: 1|true

  Whether to echo or return the drop-down. Accepts 1|true (echo) or 0|false (return).

• $selectedintdefault: 0

  Which user ID should be selected.

• $include_selectedbooldefault: false

  Whether to always include the selected user ID in the drop- down.

• $namestringdefault: 'user'

  Name attribute of select element.

• $idstringdefault: is the value of $name

  ID attribute of the select element.

• $classstringdefault: empty

  Class attribute of the select element.

• $blog_idintdefault: is ID of the current blog

  ID of blog (Multisite only).

• $whostringdefault: empty (all users)

  Deprecated, use $capability instead. Which type of users to query. Accepts only an empty string or 'authors'.

• $rolestring|string[]default: empty

  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 <em>each</em> role.

• $role__instring[]default: empty array

  An array of role names. Matched users must have at least one of these roles.

• $role__not_instring[]default: empty array

  An array of role names to exclude. Users matching one or more of these roles will not be included in results.

• $capabilitystring|string[]default: empty

  An array or a comma-separated list of capability names that users must match to be included in results. Note that this is an inclusive list: users must match <em>each</em> capability. Does NOT work for capabilities not in the database or filtered via 'map_meta_cap'.

• $capability__instring[]default: empty array

  An array of capability names. Matched users must have at least one of these capabilities. Does NOT work for capabilities not in the database or filtered via 'map_meta_cap'.

• $capability__not_instring[]default: empty array

  An array of capability names to exclude. Users matching one or more of these capabilities will not be included in results. Does NOT work for capabilities not in the database or filtered via 'map_meta_cap'.

Return

string

HTML dropdown list of users.

Hooks fired · 2

2 hooks fire while wp_dropdown_users() runs, in this order:

1. 1
   apply_filters( wp_dropdown_users_args )filterline 1792 (+73 into the body)

   Filters the query arguments for the list of users in the dropdown.

2. 2
   apply_filters( wp_dropdown_users )filterline 1858 (+139 into the body)

   Filters the wp_dropdown_users() HTML output.

Uses · 12

• get_current_blog_id()Retrieves the current site ID.
• is_author()Determines whether the query is for an existing author archive page.
• get_query_var()Retrieves the value of a query variable in the WP_Query class.
• wp_parse_args()Merges user defined arguments into defaults array.
• wp_array_slice_assoc()Extracts a slice of an array, given a list of keys.
• apply_filters()Calls the callback functions that have been added to a filter hook.
• get_users()Retrieves list of users matching criteria.
• esc_attr()Escaping for HTML attributes.
• selected()Outputs the HTML selected attribute.
• get_userdata()Retrieves user info by user ID.
• _x()Retrieves translated string with gettext context.
• esc_html()Escaping for HTML blocks.

Used by · 2

• WP_Posts_List_Table::inline_edit()Outputs the hidden row displayed when inline editing
• post_author_meta_box()Displays form field with list of authors.

Source

View on Trac ↗View on GitHub ↗

1719function wp_dropdown_users( $args = '' ) {1720	$defaults = array(1721		'show_option_all'         => '',1722		'show_option_none'        => '',1723		'hide_if_only_one_author' => '',1724		'orderby'                 => 'display_name',1725		'order'                   => 'ASC',1726		'include'                 => '',1727		'exclude'                 => '',1728		'multi'                   => 0,1729		'show'                    => 'display_name',1730		'echo'                    => 1,1731		'selected'                => 0,1732		'name'                    => 'user',1733		'class'                   => '',1734		'id'                      => '',1735		'blog_id'                 => get_current_blog_id(),1736		'who'                     => '',1737		'include_selected'        => false,1738		'option_none_value'       => -1,1739		'role'                    => '',1740		'role__in'                => array(),1741		'role__not_in'            => array(),1742		'capability'              => '',1743		'capability__in'          => array(),1744		'capability__not_in'      => array(),1745	);1746 1747	$defaults['selected'] = is_author() ? get_query_var( 'author' ) : 0;1748 1749	$parsed_args = wp_parse_args( $args, $defaults );1750 1751	$query_args = wp_array_slice_assoc(1752		$parsed_args,1753		array(1754			'blog_id',1755			'include',1756			'exclude',1757			'orderby',1758			'order',1759			'who',1760			'role',1761			'role__in',1762			'role__not_in',1763			'capability',1764			'capability__in',1765			'capability__not_in',1766		)1767	);1768 1769	$fields = array( 'ID', 'user_login' );1770 1771	$show = ! empty( $parsed_args['show'] ) ? $parsed_args['show'] : 'display_name';1772	if ( 'display_name_with_login' === $show ) {1773		$fields[] = 'display_name';1774	} else {1775		$fields[] = $show;1776	}1777 1778	$query_args['fields'] = $fields;1779 1780	$show_option_all   = $parsed_args['show_option_all'];1781	$show_option_none  = $parsed_args['show_option_none'];1782	$option_none_value = $parsed_args['option_none_value'];1783 1784	/**1785	 * Filters the query arguments for the list of users in the dropdown.1786	 *1787	 * @since 4.4.01788	 *1789	 * @param array $query_args  The query arguments for get_users().1790	 * @param array $parsed_args The arguments passed to wp_dropdown_users() combined with the defaults.1791	 */1792	$query_args = apply_filters( 'wp_dropdown_users_args', $query_args, $parsed_args );1793 1794	$users = get_users( $query_args );1795 1796	$output = '';1797	if ( ! empty( $users ) && ( empty( $parsed_args['hide_if_only_one_author'] ) || count( $users ) > 1 ) ) {1798		$name = esc_attr( $parsed_args['name'] );

History

Introduced in 2.3.0. Unchanged from 6.7.7 through 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data

Generated from the wordpress-develop 6.9.7 tag, from src/wp-includes/user.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.

Corrections

Something wrong on this page? Report it and it gets fixed in the next regeneration.