How to Modify, Delete, and Add Custom User Roles in WordPress

WordPress includes five default user roles: Subscriber, Contributor, Author, Editor, and Administrator. Each role has a specific set of capabilities, making it easier to manage user permissions on your site.

However, these default roles may not always fit your site's needs. You might need to rename, delete, or add custom user roles. For example, a resource site might not need the Author or Subscriber roles. This tutorial explains how to modify, delete, and create custom user roles in WordPress.

1. Modifying a User Role

The following code example changes the display name of the 'subscriber' role to 'Visitor'.

// WordPress: Change a user role's display name
add_action('init', 'fanly_change_role_name');
function fanly_change_role_name() {
    global $wp_roles;
    if ( ! isset( $wp_roles ) ) {
        $wp_roles = new WP_Roles();
    }
    $wp_roles->roles['subscriber']['name'] = 'Visitor';
    $wp_roles->role_names['subscriber'] = 'Visitor';
}

How to Use

1. Copy the code into your theme's functions.php file.
2. Modify lines 6 and 7, replacing 'subscriber' with the target role's internal name (e.g., 'author') and 'Visitor' with your desired new display name.
3. After saving, the new name will appear in the role selector when adding or editing a user in the WordPress admin.

2. Adding a Custom User Role

Use the add_role() function to create a new role with specific capabilities.

// WordPress: Add a custom user role
add_role('custom_role', 'Custom Role', array(
    'read' => true,          // Allows reading posts/pages
    'edit_posts' => true,    // Allows editing their own posts
    'delete_posts' => false, // Prevents deleting posts
));

How to Use

1. Copy the code into your theme's functions.php file.
2. Modify the parameters:
   • 'custom_role': The internal role name (must be unique).
   • 'Custom Role': The display name shown in the admin.
   • The array: Set capabilities to true (allow) or false (deny). Refer to the WordPress Codex for a full list.
3. After saving, the new role will be available in the user management screens.

3. Deleting a User Role

Use the remove_role() function to permanently delete a role.

// WordPress: Delete user roles
remove_role( 'contributor' ); // Contributor
remove_role( 'subscriber' );  // Subscriber
// remove_role( 'author' );   // Author (commented out)
// remove_role( 'editor' );   // Editor (commented out)

How to Use & Important Warning

1. Copy the code into your theme's functions.php file.
2. Uncomment the lines for the roles you wish to delete. The example above deletes only the Contributor and Subscriber roles.
3. Warning: Deleting a role is irreversible. Before deletion, ensure no users are assigned to that role, or reassign them to another role first. Deleting a role used by existing users can cause access issues.