get_users( array $args = array() )

Retrieve list of users matching criteria.


Description Description

See also See also


Top ↑

Parameters Parameters

$args

(array) (Optional) Arguments to retrieve users. See WP_User_Query::prepare_query(). for more information on accepted arguments.

Default value: array()


Top ↑

Return Return

(array) List of users.


Top ↑

Source Source

File: wp-includes/user.php

function get_users( $args = array() ) {

	$args                = wp_parse_args( $args );
	$args['count_total'] = false;

	$user_search = new WP_User_Query( $args );

	return (array) $user_search->get_results();
}

Top ↑

Changelog Changelog

Changelog
Version Description
3.1.0 Introduced.


Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note 2 content
    Contributed by Codex

    An example using the ‘search’ field.

    <?php
    $blogusers = get_users( array( 'search' => 'john' ) );
    // Array of WP_User objects.
    foreach ( $blogusers as $user ) {
    	echo '<span>' . esc_html( $user->user_email ) . '</span>';
    }
    

    This example will find and display all users that have a user name, ID, email of “john”. You can also do wild card search by adding an * before or after your search query. For example, to search for all users that start with “jo”, you would pass something like “jo*”.

    The results will be all users whose user names, IDs, or emails that start with “jo”. The * can be placed before or after your search query. When placed before, the results will be all users that end in your query.

  2. Skip to note 4 content
    Contributed by crmunro

    An example of fetching users that match any one of an array of roles using role__in.

    <?php
    $blogusers = get_users( [ 'role__in' => [ 'author', 'subscriber' ] ] );
    // Array of WP_User objects.
    foreach ( $blogusers as $user ) {
        echo '<span>' . esc_html( $user->display_name ) . '</span>';
    }

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