wp_list_authors( string|array $args =  ): void|string

Lists all the authors of the site, with several options available.

Parameters

$argsstring|arrayoptional
Array or string of default arguments.
  • orderby string
    How to sort the authors. Accepts 'nicename', 'email', 'url', 'registered', 'user_nicename', 'user_email', 'user_url', 'user_registered', 'name', 'display_name', 'post_count', 'ID', 'meta_value', 'user_login'. Default 'name'.
  • order string
    Sorting direction for $orderby. Accepts 'ASC', 'DESC'. Default 'ASC'.
  • number int
    Maximum authors to return or display. Default empty (all authors).
  • optioncount bool
    Show the count in parenthesis next to the author’s name. Default false.
  • exclude_admin bool
    Whether to exclude the 'admin' account, if it exists. Default true.
  • show_fullname bool
    Whether to show the author’s full name. Default false.
  • hide_empty bool
    Whether to hide any authors with no posts. Default true.
  • feed string
    If not empty, show a link to the author’s feed and use this text as the alt parameter of the link.
  • feed_image string
    If not empty, show a link to the author’s feed and use this image URL as clickable anchor.
  • feed_type string
    The feed type to link to. Possible values include 'rss2', 'atom'.
    Default is the value of get_default_feed() .
  • echo bool
    Whether to output the result or instead return it. Default true.
  • style string
    If 'list', each author is wrapped in an <li> element, otherwise the authors will be separated by commas.
  • html bool
    Whether to list the items in HTML form or plaintext. Default true.
  • exclude int[]|string
    Array or comma/space-separated list of author IDs to exclude.
  • include int[]|string
    Array or comma/space-separated list of author IDs to include.

Default:''

Return

void|string Void if 'echo' argument is true, list of authors if 'echo' is false.

More Information

Displays a list of the sites’s authors (users), and if the user has authored any posts, the author name is displayed as a link to their posts. Optionally this tag displays each author’s post count and RSS feed link.

Source

function wp_list_authors( $args = '' ) {
	global $wpdb;

	$defaults = array(
		'orderby'       => 'name',
		'order'         => 'ASC',
		'number'        => '',
		'optioncount'   => false,
		'exclude_admin' => true,
		'show_fullname' => false,
		'hide_empty'    => true,
		'feed'          => '',
		'feed_image'    => '',
		'feed_type'     => '',
		'echo'          => true,
		'style'         => 'list',
		'html'          => true,
		'exclude'       => '',
		'include'       => '',
	);

	$parsed_args = wp_parse_args( $args, $defaults );

	$return = '';

	$query_args           = wp_array_slice_assoc( $parsed_args, array( 'orderby', 'order', 'number', 'exclude', 'include' ) );
	$query_args['fields'] = 'ids';

	/**
	 * Filters the query arguments for the list of all authors of the site.
	 *
	 * @since 6.1.0
	 *
	 * @param array $query_args  The query arguments for get_users().
	 * @param array $parsed_args The arguments passed to wp_list_authors() combined with the defaults.
	 */
	$query_args = apply_filters( 'wp_list_authors_args', $query_args, $parsed_args );

	$authors     = get_users( $query_args );
	$post_counts = array();

	/**
	 * Filters whether to short-circuit performing the query for author post counts.
	 *
	 * @since 6.1.0
	 *
	 * @param int[]|false $post_counts Array of post counts, keyed by author ID.
	 * @param array       $parsed_args The arguments passed to wp_list_authors() combined with the defaults.
	 */
	$post_counts = apply_filters( 'pre_wp_list_authors_post_counts_query', false, $parsed_args );

	if ( ! is_array( $post_counts ) ) {
		$post_counts       = array();
		$post_counts_query = $wpdb->get_results(
			"SELECT DISTINCT post_author, COUNT(ID) AS count
			FROM $wpdb->posts
			WHERE " . get_private_posts_cap_sql( 'post' ) . '
			GROUP BY post_author'
		);

		foreach ( (array) $post_counts_query as $row ) {
			$post_counts[ $row->post_author ] = $row->count;
		}
	}

	foreach ( $authors as $author_id ) {
		$posts = isset( $post_counts[ $author_id ] ) ? $post_counts[ $author_id ] : 0;

		if ( ! $posts && $parsed_args['hide_empty'] ) {
			continue;
		}

		$author = get_userdata( $author_id );

		if ( $parsed_args['exclude_admin'] && 'admin' === $author->display_name ) {
			continue;
		}

		if ( $parsed_args['show_fullname'] && $author->first_name && $author->last_name ) {
			$name = sprintf(
				/* translators: 1: User's first name, 2: Last name. */
				_x( '%1$s %2$s', 'Display name based on first name and last name' ),
				$author->first_name,
				$author->last_name
			);
		} else {
			$name = $author->display_name;
		}

		if ( ! $parsed_args['html'] ) {
			$return .= $name . ', ';

			continue; // No need to go further to process HTML.
		}

		if ( 'list' === $parsed_args['style'] ) {
			$return .= '<li>';
		}

		$link = sprintf(
			'<a href="%1$s" title="%2$s">%3$s</a>',
			esc_url( get_author_posts_url( $author->ID, $author->user_nicename ) ),
			/* translators: %s: Author's display name. */
			esc_attr( sprintf( __( 'Posts by %s' ), $author->display_name ) ),
			$name
		);

		if ( ! empty( $parsed_args['feed_image'] ) || ! empty( $parsed_args['feed'] ) ) {
			$link .= ' ';
			if ( empty( $parsed_args['feed_image'] ) ) {
				$link .= '(';
			}

			$link .= '<a href="' . get_author_feed_link( $author->ID, $parsed_args['feed_type'] ) . '"';

			$alt = '';
			if ( ! empty( $parsed_args['feed'] ) ) {
				$alt  = ' alt="' . esc_attr( $parsed_args['feed'] ) . '"';
				$name = $parsed_args['feed'];
			}

			$link .= '>';

			if ( ! empty( $parsed_args['feed_image'] ) ) {
				$link .= '<img src="' . esc_url( $parsed_args['feed_image'] ) . '" style="border: none;"' . $alt . ' />';
			} else {
				$link .= $name;
			}

			$link .= '</a>';

			if ( empty( $parsed_args['feed_image'] ) ) {
				$link .= ')';
			}
		}

		if ( $parsed_args['optioncount'] ) {
			$link .= ' (' . $posts . ')';
		}

		$return .= $link;
		$return .= ( 'list' === $parsed_args['style'] ) ? '</li>' : ', ';
	}

	$return = rtrim( $return, ', ' );

	if ( $parsed_args['echo'] ) {
		echo $return;
	} else {
		return $return;
	}
}

Hooks

apply_filters( ‘pre_wp_list_authors_post_counts_query’, int[]|false $post_counts, array $parsed_args )

Filters whether to short-circuit performing the query for author post counts.

apply_filters( ‘wp_list_authors_args’, array $query_args, array $parsed_args )

Filters the query arguments for the list of all authors of the site.

Changelog

VersionDescription
1.2.0Introduced.

User Contributed Notes

  1. Skip to note 2 content

    Authors full names and number of posts
    This example displays a list of the site’s authors with the full name (first and last name) plus the number of posts for each author. Note the output is in descending order by the post count, and limited to three (3) authors/users. Also, and by default, it excludes the admin author, hides authors with no posts, and does not display the RSS feed or image.

    wp_list_authors( array(
    	'show_fullname' => 1,
    	'optioncount'   => 1,
    	'orderby'       => 'post_count',
    	'order'         => 'DESC',
    	'number'        => 3
    ) );

    Example output:

    Andrew Anderson (48)
    Harriett Smith (42)
    Sally Smith (29)

You must log in before being able to contribute a note or feedback.