How to create WordPress user taxonomies

In this article, we will explore how we can create custom WordPress taxonomies for users. WordPress taxonomies organize objects into categories or tags. User taxonomies have custom attributes for efficient management and segmentation. personalized user experiences within a WordPress website.

wordpress user taxonomy

What is a taxonomy in WordPress

Taxonomies can organize and group objects in WordPress, such as posts, pages, and users, into structured categories or tags. Examples of core WordPress taxonomies are post categories and tags. WordPress provides various functions that allow developers to create custom taxonomies. They can be registered to any kind of object, including custom post types and users.

When it comes to user taxonomies, they can include various custom-defined attributes, allowing for efficient administration, user segmentation, and personalized user experiences within a WordPress website.

The Users Insights Groups feature uses taxonomies behind the scenes to group and tag users. In this tutorial, we will show you how this is achieved programmatically, including the process of registering a user taxonomy and assigning terms from this taxonomy to users.

Users Insights Group Taxonomy

The PHP code discussed below can be added to the functions.php file of your child theme or in a custom plugin.

Registering the user taxonomy

First, we’ll use the register_taxonomy() function to register our custom taxonomy. We will register a custom taxonomy with the name “Group” and slug “group” that can be assigned to users.

function my_register_user_group(){
      'public' => false,
      'show_ui' => true,
      'labels' => array('name' => 'User Groups', 'singular_name' => 'User Group'),
      'capabilities' => array(
        'manage_terms' => 'edit_users',
        'edit_terms'  => 'edit_users',
        'delete_terms' => 'edit_users',
        'assign_terms' => 'edit_users',

add_action( 'init', 'my_register_user_group');

Here is a detailed explanation of the code used in this snippet to create a custom taxonomy:

  • First, we set the taxonomy slug to ‘group’. If you change this slug, it is important to change every occurrence of the ‘group’ slug in the next steps.
  • We set the ‘public’ option to false, as in this particular case, the taxonomy is not intended for public (front-end) use. If you need this taxonomy to be publicly available, you can set this option to true.
  • We also set the ‘show_ui’ option to true so that we can manage the taxonomies from the admin interface. You can set this option to false if you don’t need the admin interface.
  • The taxonomy name is set to ‘User Group’
  • Set the capabilities to ‘edit_users’ so that only users who can edit other users can manage the user taxonomies. You can change this capability based on your requirements.

At this point, we should have a page that is accessible via this path in the dashboard:

Gain Valuable Insights From Your WordPress User Data

Adding the user taxonomy to the admin dashboard menu

The next step is to add the “User Groups” page under the Users menu using the add_submenu_page() function. This will allow us to create new taxonomy terms from the admin dashboard user interface.

function my_add_user_group_to_menu(){
  add_submenu_page( 'users.php', 'User Groups', 'User Groups', 'edit_users', 'edit-tags.php?taxonomy=group' );
add_action( 'admin_menu', 'my_add_user_group_to_menu' );

Again, we use the ‘edit_users’ capability, which can be changed based on your requirements.

Creating WordPress user taxonomy terms programmatically

The taxonomy terms are labels used to categorize and organize the users. If you prefer not to use the admin interface, or for any reason you need to create user taxonomy terms dynamically, you can use the wp_insert_term() function:

wp_insert_term('Members', 'group');

In this example, we have created a new term called “Members” in our custom user taxonomy “group”.

Adding taxonomy terms to users

Now that we can create User Group terms, we can add them to users using the wp_set_object_terms() function:

wp_set_object_terms($user_id, array('members', 'leads'), 'group', true);

This code snippet adds (appends) the user group terms with slugs “members” and “leads” to the user with the given user ID ($user_id). If you need to replace all terms from this taxonomy, you can set the last parameter to false:

wp_set_object_terms($user_id, array('members', 'leads'), 'group', false);

Removing taxonomy terms from users

To remove taxonomy terms from a user, you can use the wp_remove_object_terms() function:

// remove a single term
wp_remove_object_terms($user_id, 'members', 'group');
// remove multiple terms
wp_remove_object_terms($user_id, array('members', 'leads'), 'group');

This example illustrates how to remove both a single term and multiple terms simultaneously.

Querying users by taxonomy

Once we can assign taxonomy terms to the users, we might need to search users by the custom taxonomy terms. Searching users is most commonly performed using the WP_User_Query class or by using the get_users() function. However these two methods do not support searching by taxonomy. The solution for this case is to use the get_term_by() function. The following code fetches users associated with a specific term (‘member’) in the ‘group’ taxonomy and stores their user objects in the $users variable.

$term = get_term_by('slug', 'member', 'group');
$user_ids = get_objects_in_term( $term->term_id, 'group' );
$users = get_users(array('include' => $user_ids));

We use the get_term_by() function to retrieve a term from the ‘group’ taxonomy based on its slug (‘member’). This function returns the term object representing the term with the specified slug. After this, we use the get_objects_in_term() function to retrieve the IDs of users associated with the term obtained in the previous step. Finally, we retrieve the user objects based on the IDs obtained in the previous step.

User taxonomies in Users Insights

As mentioned above, Users Insights uses custom taxonomies behind the scenes for its Groups feature. It implements the code discussed in this article with additional UI features. For example, group taxonomy terms can be easily bulk-assigned from the user table or assigned from the user profile:

Add groups to WordPress user

Additionally, Users Insights includes powerful filters that allow you to search your users based on custom user taxonomies and combine these searches with all of theĀ available filters that the plugin provides:

Query users by custom taxonomy


In conclusion, this article has demonstrated the practical implementation of WordPress user taxonomies. By outlining the process to programmatically register user taxonomies, manipulate taxonomy terms associated with users, and effectively query users based on these taxonomies, we have explored valuable insights into managing and organizing user data within WordPress. These functionalities provide powerful tools to structure, categorize, and retrieve user information systematically, enabling more refined user management in WordPress.