Creating a custom user role

This tutorial gives additional details on how to create a new user role in WordPress. I have also added an overview of the default user roles that exist in WordPress.

Default WordPress user roles
Create a new user role
User role options
Clone the Administrator user role
Remove a user Role
Using a plugin

Default WordPress user roles

Super Admin (Multisite)
Administrator
Editor
Author
Contributor
Subscriber

Super Admin (Multisite)

Dashboard: Home, Updates, Upgrade Network.
Sites: All Sites, Add New.
Users: All Users, Add New.
Themes: Installed Themes, Add New, Theme File Editor.
Plugins: Installed Plugins, Add New, Plugin File Editor.
Settings.

Administrator

Has access to all top level and submenu items.
Dashboard: Home, Updates.
Posts: All Posts, Add New, Categories, Tags.
Media: Library, Add New.
Pages: All Pages, Add New.
Comments.
Appearance: Themes, Customize, Widgets, Menus, Header, Theme File Editor.
Plugins: Installed Plugins, Add New, Plugin File Editor.
Users: All Users, Add New, Profile.
Tools: Available Tools, Import, Export, Site Health, Export Personal Data, Erase Personal Data.
Settings: General, Writing, Reading, Discussion, Media, Permalinks, Privacy.

Editor

Has access to top level: Dashboard, Comments, Profile and Tools.
Posts: All Posts, Add New, Categories, Tags.
Media: Library, Add New.
Pages: All Pages, Add New.

Author

Has access to top level: Dashboard, Comments, Profile and Tools.
Posts: All Posts, Add New, ~~Categories,~~ ~~Tags~~.
Media: Library, Add New.
~~Pages: All Pages, Add New~~.

Contributor

Has access to top level: Dashboard, Comments, Profile and Tools.
Posts: All Posts, Add New, ~~Categories,~~ ~~Tags~~.
~~Media: Library, Add New.~~
~~Pages: All Pages, Add New~~.

Subscriber

Has access to top level: Dashboard, ~~Comments~~, Profile ~~and Tools~~.
~~Posts: All Posts, Add New, Categories, Tags.~~
~~Media: Library, Add New.~~
~~Pages: All Pages, Add New~~.

Create a new user role

/* Add a custom user role: https://codex.wordpress.org/Roles_and_Capabilities */

 $result = add_role('client', 'Client', array(
 // User role capabilities.
 'read' => true, // Access to Dashboard and Users -> Profile./
 'edit_posts' => true, 
 'delete_posts' => true,
 ));

The above Client user role capabilities are the same as the default WordPress Contributor user role.

Go to Users -> Add New -> select Role drop down and notice the new client role has been added.

User role options

// Dashboard
'read' => true,           // Access to Dashboard and Users -> Your Profile.
'update_core' => true,    // Can update core.

// Posts
'edit_posts' => true,    // Access to All Posts, Add New, Comments and comments awaiting moderation.
'create_posts' => true,  // Allows user to create new posts.
'delete_posts' => true,  // Can delete posts.
'publish_posts' => true, // Can publish posts. Otherwise they stay in draft mode.
'delete_published_posts' => true, // Can delete published posts.
'edit_published_posts' => true,   // Can edit posts.
'delete_others_posts' => true,    // Can delete other users posts.

// Categories, comments and users
'manage_categories' => true,      // Access to managing categories.

// Pages
'edit_pages' => true,             // Access to All Pages and Add New (page).
'publish_pages' => true,          // Can publish pages.
'edit_other_pages' => true,       // Can edit other users pages.
'edit_published_ pages' => true,  // Can edit published pages.
'delete_pages' => true,           // Can delete pages.
'delete_others_pages' => true,    // Can delete other users pages.
'delete_published_pages' => true, // Can delete published pages.

// Media Library
'upload_files' => true,           // Access to Media Library -> Add New.

// Comments
'moderate_comments' => true,      // Access to moderating comments. Edit posts also needs to be set to true.
'edit_comments' => false,         // Comments are blocked out for this user.

// Users
'list_users' => true,             // Can view all users.
'edit_users' => true,             // Can edit users.
'create_users' => true,           // Can create new users.
'promote_users' => true,          // Can change role of users.

// Appearance
'edit_themes_options' => true,    // Access to Appearance panel options.
'switch_themes' => true,          // Can switch themes.
'delete_themes' => true,          // Can delete themes.
'install_themes' => true,         // Can install a new theme.
'update_themes' => true,          // Can update themes.
'edit_themes' => true,            // Can edit themes.
'customize' => true,              // Gain access to customize.

// Plugins
'activate_plugins' => true,       // Access to plugins screen.
'edit_plugins' => true,           // Can edit plugins.
'install_plugins' => true,        // Access to installing a new plugin.
'update_plugins' => true,         // Can update plugins.
'delete_plugins' => true,         // Can delete plugins.

// Settings
'manage_options' => true,        // Can access Settings screens.

// Tools
'import' => true,                // Can access Tools -> Import/Export.

Explore the various options. Check out the WordPress documentation: roles and capabilities for additional information.

Clone the administrator user role

When we need a new administrator user role.

/* https://www.kvcodes.com/2015/04/wordpress-clone-user-role-to-create-new-role/
https://nazmulahsan.me/clone-or-add-new-user-roles/ Duplicate the admin user role. */

add_action('init', 'cloneUserRole');
function cloneUserRole()
{
 global $wp_roles;
 if (!isset($wp_roles))
 $wp_roles = new WP_Roles();
 $adm = $wp_roles->get_role('administrator');
 // Adding a new role with all admin caps.
 $wp_roles->add_role('admin-client', 'Admin Client', $adm->capabilities);
}

The result is seen when going to Users -> Add New. Click the Role drop down and notice the new Admin Client admin user role.

Remove a user role

To remove the Client user role we need to know the slug. To find the slug we can through the browser right click the drop down area and select Inspect to see the HTML and CSS area. Notice the below select name role, and the values (slug) of each role. Subscriber is by default selected. To remove the Client role we need to add the value client to the code.

Inspect user role to find slug in WordPress.

/* remove user roles. 
 remove_role('client');

NB! If you remove a user role which an existing user has then the role of the user will turn to – No role for this site – and you will need to set the new role of the current user.

Plugin approach to creating a custom user role

PublishPress Capabilities – User Role Access, Editor Permissions, Admin Menus.
User Role Editor – Add new roles and customize its capabilities.
User Switching – quickly swap between user accounts.
Multiple roles per user WordPress plugin – On Github.

Search by “user role” at the plugin repository at wordpress.org.