Simple User Listing

A directory list of users ready for your own custom styles

This plugin has been out in the wild for some time now and it seemed appropriate to give it a post on my blog. Once upon a time I was working on a magazine site with a lot of authors and my client wanted to display all the authors in a cool way. Every other plugin I found was too rigid in its output, either markup or CSS or both. I needed to be able to customize and style this list to fit my theme. And while the original site I working on is now defunct, Simple User Listing lives on.

Basic Usage

Once you’ve installed and activated the plugin you only have to add the shortcode to any page (or post) where you’d like to display a full list of all your blog’s users. By default the plugin will display all of the blog’s users and ‘paginate’ the list based on the “Posts per Page” setting.


A directory list of users ready for your own custom styles

A directory list of users ready for your own custom styles

Custom Templates

I created this plugin to use templates that can be overridden and customized by theme developers. There are 4 templates in the plugin’s templates folder: content-author.php, navigation-author.php, none-author.php and search-author.php. The templates should be relatively self-explanatory and I suspect most of the customizations will happen in content-author.php which is responsible for how each user in the user loop is displayed.

To modify a template simply copy the template file from the simple-user-listing/templates folder of the plugin and paste it  into a simple-user-listing folder in the root of your theme (so my-theme/simple-user-listing). Now you can change the markup any way you please and the plugin will know to use your template instead of the default.

It will be similar to template parts for post loops, except you will have access to each user’s $user object instead of the $post object. For more details on what is available in the  $user object see the Codex reference on WP_User()

Custom Lists

Simple User Listing relies on the WP_Query class and supports almost all of WP_Query’s parameters. Here’s a full list of all parameters:

'query_id' => 'simple_user_listing',
'role' => '',
'include' => '',
'exclude' => '',
'blog_id' => '',
'number' => get_option( 'posts_per_page', 10 ),
'order' => 'ASC',
'orderby' => 'login',
'meta_key' => '',
'meta_value' => '',
'meta_compare' => '=',
'meta_type' => 'CHAR',
'count_total' => true

To use any WP_Query parameter merely add it to the shortcode. For example:

List of Authors

[userlist role="author"]

List of Specific Users

[userlist include="1,2,3,4"]

Order Users by Last Name

As of version 1.5.2 meta query parameters were rolled into the core of the plugin…. well single meta queries anyway. You can sort by any any meta key (much like querying posts).

[userlist meta_key="last_name" orderby="meta_value" order="ASC"]

WP-Pagenavi Bonus

Simple User Listings works with WP-Pagenavi out of the box. Simply activate WP-Pagenavi and your user lists will be paginated with numbers instead of the default previous/next links.

Search by Display Name

By default the search relies on username, but we can change this with some trickery via the pre_user_query hook. Similar to pre_get_posts this is your last chance to change the WP_User_Query query before it is executed. I’ve built in a query_id variable so that you don’t go willy-nilly filtering all user queries which could have some unintended side effects.

Search by User Meta

And finally, I’ll try to walk you through setting up a custom search.

First we’ll create a new search-author.php template in our theme’s simple-user-listing folder. This template will have a pair of radio buttons that will allow the user to decide between traditional search and searching by a meta field…. in this case “city”, but it really could be whatever you want.

You don’t have to change your search template, but I thought it might be nice.

Next we’ll register a query variable. This belongs in your theme’s functions.php or better still a site-specific mu-plugin, so that it isn’t tied to you theme. Remember that themes are for presentation. Plugins are for manipulating data in ways that should persist through theme changes.

Technically if you don’t change the search template you don’t need to do this either, but I’m going whole-hog here. Did someone say Bacon?

And finally, we need to adjust the Simple User Listing args before they are sent to WP_Query.


That should do it. This plugin isn’t in particularly ‘active’ development. Essentially meaning that I’m not looking to add features. However, if it breaks somewhere do let me know.

I apologize in advance but I can’t help you with your custom implementations via the comments or WordPress support forums. I am open to contract work though. Please contact me if you’d like to hire me.

Let me know where you are using my plugin. I’d love to see how you are styling it!

Posted in


  1. Troy on August 5, 2014 at 10:09 pm

    Hello thanks for this wonderful plug-in. Can you please check your above code in a php editor. There are several syntax errors and a few that I’ve been unable to solve. I’d like to implement this. Thanks!

    • kathy on August 5, 2014 at 10:19 pm

      Thanks Troy, I’m glad you like it. Could you be more specific? Which blocks of code are causing you trouble?

      • Troy on August 5, 2014 at 10:59 pm

        Please try pasting your code in a php program – the program will highlight the lines with problems. I’ve attached a screenshot of the errors with the search-author.php code. It’s showing line 12, 16, 34. Similarly, there’s 2 errors with the functions code. One was just missing a “function” declaration. Thanks for your time.

        • kathy on August 6, 2014 at 6:55 am

          Everything was written in Sublime in the beginning, but may have been mangled while going through the website and changing syntax highlighters. Anyway, I have removed what I think are the offending bits. If you actually run the code with WP_DEBUG turned on then you will get notices about what the actual errors are.

  2. Aaron on September 3, 2014 at 1:43 pm

    Troy, Kathy is right in saying that something probably happened when the code was pasted on this site. I had the same syntax errors most of them were incorrect closing tags or mystery semicolons.
    Also be sure to change ALL of the method references to the correct meta key.

    Kathy, this plugin help out a lot! Cheers!

    • kathy on September 3, 2014 at 1:48 pm

      Thanks Aaron. I also changed syntax highlighters a while back so that mangled things further. Still, I thought I’d fixed it. Is the syntax still wrong? Where? I am travelling but could update it in the future.

Leave a Comment