How to Add Custom WordPress User Roles Programmatically

Although WordPress comes as one of the most easy-to-use CMS platforms, managing your website is not always a simple task. There are tons of things to learn as a WordPress beginner, from changing the site appearance to extending plugins and also adding media.

Among them, creating WordPress custom user roles becomes one of the most important tasks. Besides default roles, there may be times that you need to customize new roles with specific capabilities. It’s when you want to manage multiple content types or level-up existing roles.

While WordPress user role plugins help add custom roles effortlessly, you still can use code to create new roles manually. Without any further ado, let’s learn how to add user roles programmatically to your WordPress site.

Before digging into the detailed guide, we can briefly discuss WordPress default user roles as well as when to create custom ones.

WordPress Default User Roles

WordPress is equipped with 5 different user roles, including Admin, Editor, Author, Contributor, and Subscriber. Each has a set of permission and capabilities enabling them to take certain actions on your site. Below is a quick explanation of what each user role can and can’t do.

Admin User Role

Admins or administrators have the highest control level over your WordPress website. They can add plugins, change themes, create and publish all types of content, make updates, and more. An admin is also enabled to add new users or remove them from the site.

The site owner is set as an admin by default. Most sites have just one admin user. You can assign this role to some others if your site is really large and needs the management of multiple people.

You must pay high attention to your admin account since it’s the sitting target of hackers. Once stealing this important confidential information, they will control your site dashboard, change an important setting, or even destroy the site. It requires you to know and apply the best security methods to effectively protect it.

Editor User Role

Under the admin role is editors who know what authors and contributors are doing. Apart from creating and modifying all pages and posts, they can see all comments and edit them.

Not only admins but editors have the right to add categories and tags to posts. Still, it’s impossible for them to make other changes on the site such as installing plugins or themes.

Author User Role

These users are permitted to create, publish, edit, and delete their posts as well as uploading media files to the media library. Editing and displaying comments on their blogs is made simple for authors.

However, in terms of content management, authors have less power than editors. They’re unable to make pages live without submitting them to admins for review. Plus, the author’s work is kept separate from each other.

This role best suits in-house content writers. Editors or admins never have to touch on manually publishing blog posts which takes a lot of their time.


Unlike authors, contributors are allowed to create posts without publishing them. They don’t have the right to upload media files either. Anytime their post is live on-site, they can no longer edit or remove them.

You should assign the Contributor role to guest authors and freelance content writers to limit their access level on your site dashboard.


Subscribers have the lowest access level on your site. These users are able to create or edit their own accounts only.

They don’t have permission to do tasks like adding new pages and posts or modifying anything. Instead, they can log in to read restricted content on the membership site.

Why Creating Custom User Roles in WordPress

Default roles are enough for a simple website of a small organization. In case you own a huge organization and have different content types, customizing access privileges to users is a must.

When having many people in charge of your WordPress site management, you need a way to control what each user can (and can’t) do.

Take online course sites as an example. There should be a role for teachers and trainers to receive and run classes. You also need student roles who can view the course content.

Creating custom user roles gives you a great security measure too. Assigning users a high user role level may permit them to take actions out of their authorization, even accidentally or on purpose.

There are several cases when you need to create custom user roles. First, you plan to manage different content types. The in-house content team handles the press releases so you want guest authors to write educational blogs.

What’s more, you can level up the existing role. While users with lower roles don’t gain enough permission to finish their tasks, assigning them the higher role may risk your site security.

For instance, an SEO specialist role is recommended to fix content’s SEO scores by all authors. However, they won’t need comments or category/tag editions as editors. There should be a custom role between Editor and Author.

How to Add Custom Roles to WordPress Programmatically

Although there are free plugins enabling you to customize WordPress roles with ease, you should not always use plugins. If you’re good at coding or have some technical knowledge, you can make use of code instead.

Create a New Custom Role

Since you understand the reason behind customizing roles in WordPress with code, let’s get started by following the guide below.

We’re going to create a new role name SEO Manager which has all capabilities of authors and the ability to publish pages too. Each capability of the SEO Manager will be set as “true” in our code snippet.

Now, head to AppearanceTheme Editor in your admin dashboard and open the functions.php file under the ‘Theme Files’ menu. Then, enter this code there.

/* Create SEO Manager User Role */
    'seo_manager', //  System name of the role.
    __( 'SEO Manager'  ), // Display name of the role.
        'read'  => true,
        'delete_posts'  => true,
        'delete_published_posts' => true,
        'edit_posts'   => true,
        'publish_posts' => true,
        'upload_files'  => true,
        'edit_pages'  => true,
        'edit_published_pages'  =>  true,
        'publish_pages'  => true,
        'delete_published_pages' => false, // This user will NOT be able to  delete published pages.

Save your changes, double-check what you’ve done by going to Users, and adding a new one in the admin menu. You can use this account to log in and check the role capabilities.


Customize an Existing Role

Another way for role customization comes to adding capabilites to the default role. Simply enter this code snippet into your functions.php file.

/* Upgrade the Author Role */
function author_level_up() {
    // Retrieve the  Author role.
    $role = get_role(  'author' );  
    // Let's add a set  of new capabilities we want Authors to have.
    $role->add_cap(  'edit_pages' );
    $role->add_cap(  'edit_published_pages' );
    $role->add_cap(  'publish_pages' );
add_action( 'admin_init', 'author_level_up');

Grant Protected File Access to Custom Roles

PDA Gold, by default, enables admin users to access protected files via original URLs. If you’re protecting your WordPress media files with this plugin, fortunately, you can also let custom roles view these files without having to send them private download links.

We assume that you’ve already installed and activated the PDA Gold plugin. You can allow certain roles to access your private files directly by:

  1. Head over MediaLibrary from the admin navigation menu
  2. Hover your desired file and click ‘Protect’ under its name
  3. Hit the ‘Configure file protection’ option of that file
  4. Press the ‘Admin users’ button at the top of the popup
  5. Pick the custom role who can access your files directly

That’s it!

Creating Custom WordPress User Roles Made Simple

We now can understand clearly what each WordPress default user role can and can’t do. Besides these built-in roles, it’s possible for you to add custom ones by inserting some code snippets into the functions.php file. You can easily level up the default role by adding more capabilities with the coding method too.

We’ve also shown you how to grant custom roles direct access to private files protected by the PDA Gold plugin. All you need to do is secure the file and choose your desired roles.

You can do many other things with WordPress user roles. Check out the top 5 widely-used plugins to extend WordPress user roles and capabilities.