WP_User_Query – WordPress Snippet Generator

Use this WordPress code snippet generator to build complex argument arrays for the WP_User_Query class.

  • General
  • Users
  • Network
  • Search
  • Pagination
  • Order & Orderby











Order & Orderby


Custom User Query

// WP_User_Query arguments
${{themeSlug || 'your_theme_slug'}}_{{queryVariable || 'your_query_variable'}}_args = array( 'role' => '{{role}}','include' => array( {{includeUsers}} ),'exclude' => array( {{excludeUsers}} ),'blog_id' => '{{blogId}}','search' => 'searchString','number' => '{{maximumNumber}}','offset' => '{{offsetNumber}}','order' => '{{order}}','orderby' => '{{orderby}}',);

// Create the WP_User_Query object
${{themeSlug || 'your_theme_slug'}}_{{queryVariable || 'your_query_variable'}} = new WP_User_Query( ${{themeSlug || 'your_theme_slug'}}_{{queryVariable || 'your_query_variable'}}_args );

// User Loop
if ( ! empty( ${{themeSlug || 'your_theme_slug'}}_{{queryVariable || 'your_query_variable'}}->results ) ) {
	foreach ( ${{themeSlug || 'your_theme_slug'}}_{{queryVariable || 'your_query_variable'}}->results as $user ) {
		// do something
} else {
	// no users found


The WP_User_Query class allows developers to query users and their metadata through the wp_users and the wp_usermeta WordPress tables. It functions almost exactly like the WP_Query class, but for users. For instance, if you are running an online store or a membership site, then the WP_User_Query class makes it easy for you to search for a user without having to remember their usernames.

With this in mind, we’ve put together this code snippet generator tool that allows both developers and first-time theme developers to integrate user searching functionality into their WordPress themes. But before we begin, let’s take a closer look at what WP_User_Query is and what you can do with it.

What Is WP_User_Query and What Can I Do With It?

According to the WordPress Codex,

WP_User_Query is a class, defined in wp-includes/user.php, that allows querying WordPress database tables ‘wp_users‘ and ‘wp_usermeta‘. This class was introduced in Version 3.1 and as a result, the WP_User_Search class got deprecated.

Besides returning an  array of users, WP_User_Query can also give you general information about the query, along with the total number of users that are associated with your WordPress website. This can be especially useful if you want to implement pagination.

There are a number of different ways you can leverage WP_User_Query. Let’s take a look at some use case scenarios:

  • List all administrators (and excluding those with ID 1, 2, N).
  • Search for a user by email address, login email, or meta key.
  • Find the last X users who registered with your site.
  • Create a list of your subscribers.
  • Search for all authors who use Gmail.

Of course, there are several different scenarios that you can target with the WP_User_Query class. It depends entirely on what you’re trying to achieve.

With that out of the way, let’s take a look at how you can get started using this code snippet generator tool.

How Do I Use This WP_User_Query Snippet Generator Tool?

This WP_User_Query code snippet generator tool was designed to help developers create custom user queries for their WordPress themes without having to code them by hand. To use this tool, simply enter the values next to each field based on your preference and the tool will generate a theme-specific code snippet for you.

Let’s take a look at each individual field one at a time:

  • General Tab

    • Theme Slug: Enter your theme’s slug into this field in all lowercase letters, numbers and/or underscores. This value will be used to prefix functions and variables that would otherwise be incompatible with the WordPress core or any installed themes or plugins. Typically, this is the same string as the text domain, with all hyphens replaced by underscores.
    • Unique Query Variable Identifier: Enter a descriptive name for your query variable. It will be used to identify the query variable. The query variable identifier should be a unique name in all lowercase letters, numbers and/or underscores.
    • Include the Loop: Check this box if you’d like to have the code in the loop be processed on each post. By default, this value is set to false.
  • Users Tab

    • User Role: Enter an array (or a comma separated list) of user role names that the users must match in order to be included in the final results. You can select multiple values. By default, this value is empty.
    • Include Users: Enter the list of users to include in the final results.
    • Exclude Users: Enter the list of users to exclude in the final results.
  • Network Tab

    • Blog ID (Specify blog on network): Denotes the blog ID on a multisite environment. By default, the value is set to the current blog’s ID.
  • Search Tab

    • Search String: Enter a string. The code will search for all possible string matches on columns. You can also use the (*) wildcard before and/or after the string. This allows you to match on columns starting with, ending with, or containing the string you enter.
  • Pagination Tab

    • Max Number: This value denotes the maximum returned number of results. Enter an “int” value in this field.
    • Offset Number: Enter an “int” value in this field to offset the returned results.
  • Order & Orderby Tab

    • Orderby: Select which parameter you’d like to sort the retrieved results by. The value defaults to login.
    • Order: Choose whether to order the orderby parameters results by Ascending or Descending order. The value defaults to Ascending.

How Do I Add the Code Snippet to My Website?

The quickest way to add the generated code snippet to your WordPress site is via FTP. Start off by downloading the theme’s functions.php file to your desktop via an FTP client. Next, open it up in a text editor and paste the code from the Custom User Query section at the bottom of the file. Hit the Save button and re-upload it to your theme’s directory.

Alternatively, you can add the generated code snippet to your site by pasting it directly into your current theme’s functions.php file. Simply head over to Appearance > Editor from the admin panel, find your active theme’s functions.php file, and insert the code at the bottom of the file.


The WP_User_Query class offers a powerful way to query users and their metadata. We hope that this code snippet generator tool helps you integrate user searching functionality in your WordPress themes and saves you some time and effort from having to hand-code it yourself.

Do you have any questions about the WP_User_Query code snippet generator tool? Which use-case scenarios are you looking to target with this tool? Let us know in the comments section below!

Written exclusively for

Nimbus Themes Publishing Logo

About the Author

Evan Scoboria is the co-founder, and developer at Shea Media LLC, the team behind Nimbus Themes, this magazine, and a bunch of very happy clients. He co-founded Shea Media with his wife Kendall in 2009. Evan enjoys hunting, fishing, code, cycling, and most of all WordPress!

Read all posts

Leave a Reply

Your email address will not be published. Required fields are marked *