Custom WordPress and WooCommerce Development

A directory list of users, showing avatar, title, and number of posts, for each author

Simple User Listing

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.

// Switch user search from user_login to display_name via query_where 
function kia_search_users_by_display_name( $query ) {

  if ( isset( $query->query_vars['query_id'] ) && $query->query_vars['query_id'] == 'simple_user_listing' ) {
     $query->query_where = str_replace( "user_login", "display_name", $query->query_where );

add_action( 'pre_user_query', 'kia_search_users_by_display_name' ); 

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.

 * The Template for displaying Author Search
if ( ! defined( 'ABSPATH' ) ) exit; // Exit if accessed directly

$search = get_query_var( 'as' ) ? get_query_var( 'as' ) : ''; 
$method = get_query_var( 'method' ); 
$method = $method && in_array( $method, array( 'default', 'city' ) ? $method : 'default';


<div class="author-search">

<h2><?php _e('Search authors by user name or by city');?></h2>

<form method="get" id="sul-searchform" action="<?php the_permalink(); ?>">
  <label for="as" class="assistive-text"><?php _e( 'Search' ); ?></label></p> 

  <p><input type="radio" name="method" value="default" <?php checked( $method, 'default' ); ?> /> <?php _e( 'By Username' );?></p>
  <p><input type="radio" name="method" value="city" <?php checked( $method, 'city' );?> /> <?php _e( 'By City' );?></p>

  <p><input type="text" class="field" name="as" id="sul-s" placeholder="<?php _e('Search Authors');?>" value="<?php echo $search;?>" /></p>

  <p><input type="submit" class="submit" id="sul-searchsubmit" value="<?php _e('Search Authors');?>" /?></p>

if( $search ){ ?>
    <h2><?php printf( __('Search Results for: %s'), '<em>;' . $search .'</em>;' );?></h2>;
    <a href="<?php the_permalink();"?>;<?php _e('Back To Author Listing');?></a?>;
<?php } <?php

</div><!-- .author-search --> 

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?

// register an additional SUL search variable
function kia_search_users_allowed_vars( $vars ) {
  $vars[] = 'method';
  return $vars;
add_filter( 'sul_user_allowed_search_vars', 'kia_search_users_allowed_vars' );

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

// Switch the WP_User_Query args to a meta search if "by company" is selected function 
function kia_meta_search( $args ){

  $method = ( get_query_var( 'method' ) == 'company' ) ? 'company' : 'name';
  $search = ( isset( $_GET['as'] ) ) ? sanitize_text_field( $_GET['as'] ) : false;

  // if set to search by company switch to a meta query
  if ( $search &amp;&amp; $method == 'company' ){
    $args['search'] = ''; //kill default search
    $args['query_id'] = 'simple_user_listing_meta';
    $args['meta_key'] = 'company_name';
    $args['meta_value'] = $search;
    $args['meta_compare'] = 'LIKE';

  return $args;
add_filter('sul_user_query_args', 'kia_meta_search'); 


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!


8 responses to “Simple User Listing”

  1. 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!

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

      1. 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.

        1. 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. 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!

    1. 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.

  3. Prior to wordpress version 5, the plug-in used to filter according to meta key and value. And since upgrading, it doesn’t seem to work anymore. I’ve troubleshoot the plug-in and the values are definitely still being inserted, but the meta_query does not seem to be working? I am using wordpress version 5.3.2.

    1. for anyone reading… and interested in queries not displaying as you’d expect, note some membership plugins will filter the user query args. Follow our conversation here: