by
HelgaTheViking
5 (17 reviews)
Simple User Listing
A shortcode for displaying paginated lists of users.
Simple User Listing ranks #7,236 among WordPress.org plugins with 900+ active installations, a 5/5 rating from 17 reviews, and was last updated Feb 21, 2025. Data from WordPress.org, refreshed twice daily — see methodology.
Tested up to WP 6.7 (Current: 7.1)
v2.0.4
Current Version v2.0.4
Updated 1 year ago
Last Update on 21 Feb, 2025
Refreshed 16 hours ago
Last Refreshed on
Top 10% by installs
No update in over a year
Rank
#7,236
+10 this week
Active Installs
900+
-6.4%
KW Avg Position
137
3 worse
Downloads
48K
+2 today
Support Resolved
0%
—
No change
Rating
100%
Review 5 out of 5
5
(17 reviews)
Next Milestone 1K
900+
1K+
227
Ranks to Climb
-
Growth Needed
8,000,000
Active Installs
Pro
Unlock Exact Install Count
See the precise estimated active installs for this plugin, calculated from real-time ranking data.
- Exact install estimates within tiers
- Track install growth over time
- Milestone progress predictions
Need 39 more installs to reach 1K+
Rank Changes
Current
#7,236
Change
Best
#
Downloads Growth
Downloads
Growth
Peak
Upgrade to Pro
Unlock 30-day, 90-day, and yearly download history charts with a Pro subscription.
Upgrade NowReviews & Ratings
5.0
17 reviews
Overall
100%
5
17
(100%)
4
0
(0%)
3
0
(0%)
2
0
(0%)
1
0
(0%)
Security History
Source: WPVulnerability1 known vulnerability on record · 0 in the last 24 months · checked 1 month ago
-
Simple User Listing [simple-user-listing] < 1.9.3
CVE-2023-32298 · Fixed in v1.9.3
Track This Plugin
Get detailed analytics, keyword tracking, and position alerts delivered to your inbox.
Start Tracking FreePlugin Details
- Version
- 2.0.4
- Last Updated
- Feb 21, 2025
- Requires WP
- 6.1.0+
- Tested Up To
- 6.7
- PHP Version
- N/A
- Author
- HelgaTheViking
Support & Rating
- Rating
- ★ ★ ★ ★ ★ 5
- Reviews
- 17
- Support Threads
- 0
- Resolved
- 0%
Keywords
Upgrade to Pro
Unlock keyword rankings, search positions, and detailed analytics with a Pro subscription.
Upgrade Now
TL;DR
AI summary of the plugin's readmeThis plugin is for theme developers and site owners who need to display a list of their site's users. It solves the problem of showing a paginated user list that can be customized and styled to match a theme using overridable templates.
- Shortcode for user listing
- Paginated list of users
- Overridable template files
- Customizable via shortcode parameters
- Uses Posts per Page setting
Frequently Asked Questions
Common questions about Simple User Listing
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()
There are two ways to remove the search input. The search is added to a hook by the plugin, so you can remove it by adding the following to your theme's functions.php file: function remove_SUL_search() { remove_action( 'simple_user_listing_before_loop', 'sul_template_user_search' ); } add_action( 'simple_user_listing_before_loop', 'remove_SUL_search', 5 ); Or you could copy the search-author.php from the plugin's template folder to a simple-user-listing folder in your theme (so simple-user-listing/searcch-author.php) and remove all the code from it so that it is blank.
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', // This allows for targeted filtering of pre_get_user which allows for very custom queries. 'role' => '', // Multiple roles can be defined in a comma separated list [userlist role="infield,outfield"] 'role__in' => '', // Multiple roles can be defined in a comma separated list 'role__not_in' => // Multiple roles can be defined in a comma separated list 'include' => '', // Multiple user IDs can be defined in a comma separated list 'exclude' => '', // Multiple user IDs can be defined in a comma separated lis '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, 'template' => 'author' // Corresponds to content-author.php template, can accept different templates per shortcode.
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"]
While you could modify the search-author.php template, if you are only searching by one field it isn't really neccessary. You will, however, need to modify the shortcode's arguments for WP_User_Query. You can do that 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['as']) ) ? sanitize_text_field($_GET['as']) : 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'] = 'last_name'; $args['meta_value'] = $search; $args['meta_compare'] = '='; // Need to unset the original search args. if ( isset( $args['search'] ) ) unset($args['search']); } return $args; } add_filter( 'sul_user_query_args', 'kia_meta_search' ); Now the search will return users that match the entered "last_name". You can adjust as needed or use the meta_query array for more complicated meta queries.
By default the WordPress search relies on username, though wih the search_columns parameter can be made to search the user's email or ID. Frankly, I think this is weird, but that's how WordPress works. It is much more useful to search by the user's display name, however this requires 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' );
It isn't worth the effort to get the shortcode parameters to handle complex arrays. And in the end it isn't necessary as there are several filters in place to permit you to run a complex query. The key will be using the query_id parameter. For example you could pass a specific ID via shortcode: [userlist query_id="my_custom_meta_query"] And then in your theme's functions.php or a site-specific plugin, you could filter the user query args: add_filter( 'sul_user_query_args', 'sul_custom_meta_query', 10, 2 ); function sul_custom_meta_query( $args, $query_id ) { // Checking the query ID allows us to only target a specific shortcode. if ( $query_id === 'my_custom_meta_query' ) { $args['meta_query'] = array( 'relation' => 'OR', array( 'key' => 'billing_city', 'value' => 'oslo', 'compare' => '=', 'type' => 'CHAR', ), array( 'key' => 'first_name', 'value' => 'bobby', 'compare' => '=', 'type' => 'CHAR', ) ); } return $args; } For complex queries, you will want to read the WP Codex reference on WP_User_Query.
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.
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. S2 Member Conflicts | 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' );
