WP_User_Query Generator
Build a WP_User_Query: roles, capabilities, search, meta conditions, ordering and the fields to select, without loading every user on the site.
<?php
/**
* Users matching the arguments below.
*/
$args = array(
'role' => 'author',
'orderby' => 'display_name',
'order' => 'ASC',
'number' => 20,
'count_total' => false,
);
$query = new WP_User_Query( $args );
foreach ( $query->get_results() as $user ) {
echo esc_html( $user->display_name );
}
Output is valid and updates as you type.
Fix the highlighted fields to update the output.
Pick the roles, the filters and how much of each user you actually need, and the generator writes the WP_User_Query arguments with the two settings that keep it from loading the whole user table.
How to use
- Match on a capability rather than a role name where you can. A site that renames
authortocontributor_probreaks a role query and not a capability one. - Set a number. The default here is 20;
-1means every user, which on a membership site is the query that takes the site down. - Ask for IDs when IDs are all you need. Building a
WP_Userobject per row is most of the cost of a user query. - Name the search columns. Searching every column runs a
LIKEagainst four of them, and the email column is usually the one you meant. - Leave the total count off unless you are paginating. It is a second query.
Example
Editors and authors, ordered by name, IDs only:
$args = array(
'role__in' => array_map( 'trim', explode( ',', 'editor, author' ) ),
'orderby' => 'display_name',
'order' => 'ASC',
'number' => 20,
'fields' => 'ID',
'count_total' => false,
);
$query = new WP_User_Query( $args );role__in is any of the listed roles. A user with both roles appears once, not twice.
Pitfalls
number => -1loads every matching user into memory, each as a full object with their meta. It is the single most common cause of a slow admin page.rolematches users who have that role. On multisite, users with no role on the current site are excluded, which surprises people looking for a user they know exists.searchis an exact match unless you wrap the term in asterisks.*smith*matches inside the value;smithdoes not.- Searching with no
search_columnsruns aLIKEagainst login, email, nicename and display name at once. orderby => post_countadds a join and a count per user. On a large site it is far more expensive than it looks.meta_keywithmeta_valueis one condition. Anything more needsmeta_query, and each clause is another join on usermeta.count_totalis on by default and costs a second query. Turn it off unless you are showing “page 2 of 7”.- On multisite,
WP_User_Querysearches the current site’s users unless you passblog_id => 0, which searches the network.
Compatibility
WP_User_Query has been in WordPress since 3.1, role__in and role__not_in since 4.4, and the capability argument since 5.9. get_users() is a thin wrapper that returns the results directly. The generated code targets PHP 7.0 and up, and the tool runs entirely in your browser.
Frequently asked questions
Why is my user missing from the results?
blog_id => 0 to search the whole network.role or capability?
How do I paginate?
number and paged, leave count_total on, and read $query->get_total() for the number of pages.Is get_users() different from WP_User_Query?
How do I query several meta conditions?
meta_query with an array of clauses. The same rules as post meta apply, including one join per clause.