in An Introduction to WP_User_Query Class - WP Smith

An Introduction to WP_User_Query Class

Recently, I created this argument guide for WP_User_Query Class, similar to the existing WP_Query Class guide by Mark Luetke.

Some Basic Examples

Here’s a basic usage example:

Here’s a basic usage example for all users except authors:

Here’s a basic usage example for all users except editors and administrators:

Modifying the Query

However, there is more to this than the basic query, just like WP_Query. Once the query has been prepared, you can easily access the query via pre_user_query hook. However, unlike WP_Query, by default, there is no way (no method like WP_Query::is_main_query()) to distinguish between user queries with WP_User_Query as one would do on pre_get_posts.

So for a complicated example: if we want to query users, control which query we change, and order (say) by the last name user meta field or some other user meta, we are stuck with two basic approaches to modifying the query and only the query you wish to modify.

Approach #1 (Not the best IMHO)

First, you could modify the query directly through the WP_User_Query object. Though the PHP docs claims that WP_User_Query::query() is a private function, it really isn’t. So you can do something like this:

Please note the Caveat: This creates 2 queries and any use of this code should also use site transients.

Basically this code, makes one query, with the original arguments. Then we modify the query arguments in the object and the re-execute the query method, by-passing the sanitizing prepare method. Going this route could drastically hurt your site both in performance and simply breaking the site.

Side Note: $author_query = new WP_User_Query(); doesn’t actually prepare or run the query. It creates an object that looks like this:

WP_User_Query Object
    [results] => 
    [total_users] => 0
    [query_fields] => 
    [query_from] => 
    [query_where] => 
    [query_orderby] => 
    [query_limit] => 

Approach #2 (The better approach)

Second (and by far the better way), you can add an identifier argument (here: query_id), which WordPress retains as a query_var.

WP_User_Query Public Methods

WP_User_Query has two declared public methods: WP_User_Query::get_results() and WP_User_Query::get_total().

In both of these public methods, they simply return a parameter. In essence, the following two examples are the same for getting/accessing the results of the query:
$author_query = new WP_User_Query( $args );
$authors = $author_query->get_results();
$author_query = new WP_User_Query( $args );
$authors = $author_query->results;

Likewise, the same is true for get_total() method. The following two examples are the same for getting the total number of users from the WP_User_Query:
$author_query = new WP_User_Query( $args );
$total = $author_query->get_total();
$author_query = new WP_User_Query( $args );
$total_authors = $author_query->total_users;

About Travis Smith

As a WordPress Enthusiast, Travis writes about his journey in WordPress trying to help other WordPress travelers and enthusiasts with tutorials, explanations, & demonstrations of the things he learns.


  1. thanks for doing this! I love the query_arg trick to identify the main query :)

  2. Excellent one, Travis.

    I’d never thought of the query_id trick for identifying your unique query. Props.

    FYI, your comment form tab index is getting confused with your sidebar form.

  3. Fantastic – just wanted to say thanks for the orderby example, had been struggling with that! No idea why WP_User_Query doesn’t have the orderby => meta_value that WP_Query does…

  4. Thank you! This is awesome. Pippin is correct that tabbing through the form jumps me all over the page.

    Also, wanted to ask quickly about the meta_key called wpsand_capabilities in the examples for everyone “but” certain roles. Should that be wp_capabilities or is that specific to your database somehow?

  5. Why won’t this work with meta_query? I need to sort my list by last name, but I also have to check yet another met key/value set (for approval in the listing). I can get this to work as ou state above, but when I pop it into a meta_query (so I can look for last name AND for the meta_key = “approved” AND meta_value = “yes”) it doesn’t work anymore.

    How would you make that work?

  6. Re-ordering my users by last name was exactly what I needed, so this has saved me a lot of frustration. I thought I was going to have to painstakingly recreate my query. Thanks so much.

Leave a Reply

%d bloggers like this: