Ready to get started?Download WordPress

Plugin Directory

Simple User Listing

A shortcode for displaying paginated lists of users.

I can't get the search users to work?

The search form will not work with the default permalinks. Try changing your permalinks to some other structure. The reason is form submits via the GET method and so adding those parameters to the URL seem to clash with the parameters already on the URL from the default permalink setup.

The search doesn't respect the shortcode parameters

Likely you are experiencing a conflict with another plugin, specifically one that is filtering pre_user_query to modify all user queries. The S2 Member plugin is a known culprit of this. To disable S2 Member's modifications on all Simple User Listing lists, add the following to your theme's functions.php or to a site-specific plugin. Ensure you are using at least SUL 1.5.3.

function kia_protect_sul_from_s2(){
    remove_action('pre_user_query', 'c_ws_plugin__s2member_users_list::users_list_query');
add_action( 'simple_user_listing_before_loop', 'kia_protect_sul_from_s2' );

function kia_restore_s2(){
    add_action('pre_user_query', 'c_ws_plugin__s2member_users_list::users_list_query');
add_action( 'simple_user_listing_after_loop', 'kia_restore_s2' );

How Can I Customize the User Query?

Simple User Listing supports most of the parameters of the WP_User_Query class as parameters for the shortcode. For example you can pass it a role defining which type of users you'd like to list. You can also adjust the number of users displayed per page. Roles must be in lowercase.

[userlist role="author" number="5"]

As of version 1.2 you can now sort the user list by and of the sort parameters supported by WP_User_Query(). For example, the following would list your users based on number of posts written, with the highest first.

[userlist orderby="post_count" order="DESC"]

As of version 1.4 you can now list users by a meta key. Be careful with this as this is not exactly an efficient query.

[userlist meta_key="foo" meta_value="widgets"]

As of version 1.4.2 you can now include and exclude users with a comma separated list of IDs.

[userlist exclude="1,2,3"]

The full list of supported parameters (shown with default value) is:

'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 know which values are supported, please see the WP Codex reference on WP_User_Query.

How Can I Sort the Users by Last Name?

As of verison 1.5.2 you could simply use the following as your shortcode:

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

How Can I Customize the HTML/text, etc?

The whole reason I wrote this was that other similar plugins had too much control over the output. You can style the output anyway you'd like by adding your own template parts to your theme.

Copy the files you wish to modify from the simple-user-listing/templates folder of the plugin and paste them 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. 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()

Does Simple User Listing work with WP_Pagenavi?

Yes! WP Pagenavi supports pagination for WP_User_Query and I configured the navigation-author.php template to automatically use WP Pagenavi if it is installed and activated.

How can I setup custom search? (search by a meta field)

First you need to change your search form. You can do that by creating a new search-authors.php template in the simple-user-listing folder of your theme.

For example, if I wanted to search by the meta field "billing_city" I would have my search template look like the following:

 * The Template for displaying Author Search
 * Place this file in your theme
 * yourtheme/simple-user-listing/search-author.php

if ( ! defined( 'ABSPATH' ) ) exit; // Exit if accessed directly

$search = ( get_query_var( 'billing_city' ) ) ? get_query_var( 'billing_city' )  : '';

global $sul_users;

<div class="author-search">
  <h2><?php _e('Search authors by city' ,'simple-user-listing');?></h2>
        <form method="get" id="sul-searchform" action="<?php the_permalink() ?>">
            <label for="as" class="assistive-text"><?php _e('Search' ,'simple-user-listing');?></label>

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

            <input type="submit" class="submit" id="sul-searchsubmit" value="<?php _e('Search Authors' ,'simple-user-listing');?>" />
    if( $search ){ ?>
        <h2 ><?php printf( __('Search Results for: %s' ,'simple-user-listing'), '<em>' . $search .'</em>' );?></h2>
        <a href="<?php the_permalink(); ?>"><?php _e('Back To Author Listing' ,'simple-user-listing');?></a>
    <?php } ?>
</div><!-- .author-search -->

Next you'll need to modify the shortcode's arguments for WP_User_Query. You can do that by filtering sul_user_query_args and then adding your parameters to the Simple User Listing's whitelist by filtering sul_user_query_args.

Add the following to your theme's functions.php:

 * Place this in your theme's functions.php file
 * Or a site-specific plugin
// Switch the WP_User_Query args to a meta search
function kia_meta_search( $args ){

  // this $_GET is the name field of the custom input in search-author.php
    $search = ( isset($_GET['billing_city']) ) ? sanitize_text_field($_GET['billing_city']) : false ;

    if ( $search ){
        // if your shortcode has a 'role' parameter defined it will be maintained
        // unless you choose to unset the role parameter by uncommenting the following
        //  unset( $args['role'] );
        $args['meta_key'] = 'billing_city';
        $args['meta_value'] = $search;
        $args['meta_compare'] = '=';

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

// Register query var and whitelist with Simple User Listing
function kia_search_vars( $vars ){
    $vars[] = 'billing_city';
    return $vars;
add_filter('sul_user_allowed_search_vars', 'kia_search_vars');

Now the search will return users that match the entered "billing_city". You can adjust as needed for more complicated meta queries.

Requires: 3.8 or higher
Compatible up to: 3.8.3
Last Updated: 2014-2-9
Downloads: 5,604


5 stars
5 out of 5 stars


0 of 2 support threads in the last two months have been resolved.

Got something to say? Need help?


Not enough data

0 people say it works.
0 people say it's broken.