Query Users

This page covers how to query WordPress users using get_users().

Arguments follow the WP_User_Query API.

Basic usage

{% for user in get_users({'role': 'author'}) %}
    <h3>{{ user.name }}</h3>
{% endfor %}

Common arguments

Argument	Description	Example
role	User role	'author', 'editor', 'subscriber'
role__in	Multiple roles (OR)	['editor', 'administrator']
role__not_in	Exclude roles	['subscriber']
orderby	Sort field	'display_name', 'registered', 'post_count'
order	Sort direction	'ASC', 'DESC'
number	Limit results	10
has_published_posts	Only users with posts	true, ['post'], ['post', 'page']
include	Include specific IDs	[1, 2, 3]
exclude	Exclude specific IDs	[1]
search	Search by name/email	'*john*'

Real-world patterns

Team page

{% for user in get_users({
    'role': 'author',
    'orderby': 'display_name',
    'order': 'ASC'
}) %}
    <div class="team-member">
        <img src="{{ user.avatar(150) }}" alt="{{ user.name }}">
        <h3>{{ user.name }}</h3>
        <p>{{ user.description }}</p>
    </div>
{% endfor %}

Author list with post counts

{% for user in get_users({
    'has_published_posts': ['post'],
    'orderby': 'post_count',
    'order': 'DESC'
}) %}
    <a href="{{ user.link }}">
        <img src="{{ user.avatar(48) }}" alt="{{ user.name }}">
        <span>{{ user.name }}</span>
    </a>
{% endfor %}

Contributors section (multiple roles)

{% for user in get_users({
    'role__in': ['author', 'editor', 'contributor'],
    'orderby': 'display_name'
}) %}
    <div class="contributor">
        <img src="{{ user.avatar(64) }}" alt="{{ user.name }}">
        <h4>{{ user.name }}</h4>
        <span>{{ user.meta('job_title') }}</span>
    </div>
{% endfor %}

Staff directory with custom fields

{% for user in get_users({
    'role': 'staff',
    'orderby': 'display_name',
    'order': 'ASC'
}) %}
    <div class="staff-card">
        <img src="{{ user.avatar(120) }}" alt="{{ user.name }}">
        <h3>{{ user.name }}</h3>
        <span class="department">{{ user.meta('department') }}</span>
        <span class="phone">{{ user.meta('phone') }}</span>
        <a href="mailto:{{ user.email }}">{{ user.email }}</a>
    </div>
{% endfor %}

Simple author box (single post)

This doesn't need a loop — use the author provider directly on a single post template:

<div class="author-box">
    <img src="{{ author.avatar(96) }}" alt="{{ author.name }}">
    <h4>{{ author.name }}</h4>
    <p>{{ author.description }}</p>
    <a href="{{ author.link }}">All posts by {{ author.first_name }}</a>
</div>

Common mistake

get_users() without a role argument returns all users on the site, including subscribers. On a site with thousands of registered users (e.g., a membership site), this can be very slow. Always filter by role or use has_published_posts to limit results.

Next steps

• User provider — all fields available on user items
• get_posts() — query posts by a specific author
• Loop — loop concept and data sources