Edition note: Free supports the single-user {user} tag with one exact user, id, name, or username selector. With no selector it uses the currently logged-in user. The plural {users} tag, multiple values, and the filters on this page are Pro features.

As explained, you can use Filters to determine what users should be returned by the {users} Plugin Tag. The filters will determine what list of users is output, along with the Limit and Ordering.

So for instance, you can show data from the users in a certain user group that also have a specific value in a custom "subscription" field:

{users usergroup="Customer" subscription="Gold"}...{/users}

You can combine any filters to narrow down the resulting list of users. Each filter can also have multiple values, separated with a comma.
Note that values in filters should only be separated by a comma, so no extra spaces between the values.

{users usergroup="Customer,Lead" potential="Small,Medium"}...{/users}

Note: if you don't specify any filter, *all* users from the website will be returned (although with a Default Limit set to 100).

You can filter by supported user/account fields, Joomla User Profile values, published contact data, access levels, user groups, and user custom fields. The available keys are intentionally restricted; article categories, Joomla article tags, authentication secrets, and arbitrary database columns are not user filters. See the Data Tags overview for the public data groups and keys.

Let’s take a look at the most common Filters available and their respective options and features:

Users

In Pro, the plural tag can select multiple users by name, email, username, or ID:

{users name="Abigail Bennett,Brandon Carter,Clara Dawson"}...{/users}
{users email="abigail.bennett@example.com,brandon.carter@example.com,clara.dawson@example.com"}...{/users}
{users username="abigail,bcarter,dawson-clara"}...{/users}
{users id="8,27,123"}...{/users}

The combined user="..." selector accepts an ID, username, or display name. For a single exact result, Free and Pro can instead use {user id="8"}, {user username="abigail"}, or {user name="Abigail Bennett"}.

Within a plural-tag value, escape a literal comma as \,. For example:

{users name="Thomas Smith\, Jr.,Abigail Bennett"}...{/users}

User Groups

You can display multiple users by their user group. All you need to do is to place a usergroup="..." attribute in the tag:

{users usergroup="Customer,Registered,12"}...{/users}

Use either the title or ID of each user group, separating multiple groups with a comma.

Contacts

Want to only show users by certain contact information? Just filter down based on the contact name, country, or whatever:

{users contact:name="Peter"}...{/users}
{users contact:country="The Netherlands"}...{/users}

Dates

You can filter users based on the register-date, lastvisit-date, as well as custom fields of type calendar. You have various formats that you can use inside any of these date filters.

To return users that have registered at an exact Date and Time:

{users register-date="2019-02-15 09:30:00"}...{/users}

To show all users  that have registered on a specific Date (regardless of time):

{users register-date="2019-02-15"}...{/users}

To filter users by Month (for example, showing all users published in February 2019):

{users register-date="2019-02"}...{/users}

And to show all users registered in a certain Year, you can simply do:

{users register-date="2019"}...{/users}

Date Ranges

You can also show users that have registered (or last visited, or some other date field) before or after a certain Date (Time, Month and Year formats are also possible). To do this, use the "Greater or Less than..." feature as described in the Comparison Operators section:

{users register-date=">2019-02-15"}...{/users}
{users register-date="<2019"}...{/users}

The date filter even supports Date Ranges. This allows you to show results between two specific dates (Time format is also possible):

{users register-date="2018-11-14 to 2018-11-28"}...{/users}
{users register-date="2019-02-15 09:30:00 to 2019-02-15 18:30:00"}...{/users}

And you can use special Relative Dates values to return and compare results from the current day, yesterday, tomorrow, or any other date relative to today.

This, for example, allows to output all users that have registered yesterday. Or to output all users registered in the last 30 days:

{users register-date="date('yesterday')"}...{/users}
{users register-date="date('-30 days') to now()"}...{/users}

Note: All Date Filters will be adjusted correctly according to the Time Zone used on your website.

Custom Fields

You can even filter users by the value of the custom fields. You need to use the field name as the attribute key.

Let's say you have a custom field "Number of legs" that has a field name nr-of-legs and you want to filter down to users that have this value set to 3.

{users nr-of-legs="3"}...{/users}

You can also filter to users where a custom field value is greater or less than your specified value (See the Comparison Operators section for a full explanation):

{users nr-of-legs=">3"}...{/users}
{users nr-of-legs="<3"}...{/users}

Field Text

When filtering by custom field values, the condition checks the raw value saved in the database.

But in certain cases, such as lists or checkbox fields, you might want to check against the text value of the custom field instead. You can do so by adding :text after the name of the field:

{users nr-of-legs:text="Three legs"}...{/users}

Reserved Field Names

If your custom field name is called the same as a reserved attribute key already used by Users Anywhere (for example in the case of a custom field called  block or  activation ), you can filter by your custom field with that name by prepending the attribute with a field: prefix:

{users field:block="lower"}...{/users}

Or by using the field ID after the field: prefix:

{users field:9="lower"}...{/users}

Other User Data

Other supported account filters include block, register-date, lastvisit-date, send-email, last-reset-time, reset-count, require-reset, and auth-provider. Safe user parameters such as language, editor, and timezone can also be used.

This is an allowlist, not direct access to arbitrary columns in Joomla's users table. Passwords, activation tokens, MFA data, and raw account parameters are unavailable.

See the Data Tags overview for the supported public data groups and selectors.