How To Create Custom User Roles On WordPress (And Edit Capabilities)

User roles are what allow you to control which actions other users on your site can perform and what content those users have access to. By default, WordPress single site installs come with five user roles, but many plugins add additional user roles, and you’re also free to create your own user roles.

If you’re the only person with access to your site, you probably don’t need to concern yourself with user roles. But if you’re planning to allow other users to access your site, it can be helpful to learn how to create custom user roles so that you have pinpoint control over each users’ permissions.

In this post, I’m going to show you two different ways to create custom user roles on WordPress:

  • Using a free plugin called User Role Editor
  • With your own code snippet

We’ll jump right in after a short introduction to the relevant terminology…

The Difference Between WordPress User Roles And Capabilities

In this post, you’re going to encounter two important terms:

  • Role this is what you apply to an actual user account. For example, the first account at your WordPress site always has the Admin role.
  • Capability – this is an individual action that a specific user role is allowed to perform.

Each role on your site defines the specific capabilities that an account with that role is able to perform.

For example, the Author role has, in part, the following capabilities:

  • Edit posts
  • Publish posts
  • Upload files

This distinction is important because when you create your custom user roles, you’re going to do two things:

  • Create the role
  • Assign capabilities to that role

For a deeper look at this concept, I recommend that you check out the Capability vs. Role Table section at the WordPress Codex. It gives you a look at the various capabilities available to each default user role:

wordpress role and capability table

Plugins And Themes Often Add Their Own Roles And Capabilities

In the Capability vs Role Table above, you can view all of the default capabilities on your WordPress site.

Be aware, though, that many plugins will add their own capabilities and, sometimes, user roles.

For example, WooCommerce adds a new Shop Manager role, as well as a bunch of associated capabilities for managing different parts of your store.

For that reason, your WordPress site might have different roles or capabilities than you see in my screenshots below. Don’t worry – that’s normal!

How To Create Custom Roles On WordPress Using User Role Editor

User Role Editor is a popular free plugin that allows you to:

  • Create 100% new roles and assign capabilities to those roles
  • Edit the capabilities for existing roles on your site

There’s also a Pro version that adds additional functionality starting at $29. But most sites should be fine with the free version. There are also some other popular role and capability plugins – but User Role Editor is my favorite.

The plugin is listed at WordPress.org, so you can install it straight from your dashboard. Once you’ve got it ready, here’s how to use it…

Step 1: Create A New User Role

To get started, go to Users → User Role Editor.

If you want to edit an existing role, you can select it from the drop-down and skip to the next step. But assuming you want to create a new custom role, click the Add Role button:

how to create user roles in wordpress using user role editor

Then:

  • Give it a Role name. This cannot include spaces, but can include underscores. This is purely internal and won’t display in your interface.
  • Give it a Display Role Name. This is the name that humans will see and can contain normal text.
  • Optionally, choose whether to copy the capabilities from an existing role as the base for your new role.

give your new user role a name

Step 2: Add Capabilities To Role

Now, all that’s left to do is add capabilities to your new user role. To do that, all you need to do is check or uncheck the various boxes:

add capabilities to new user role

There are two things to pay attention to in this interface:

  • By checking the Show capabilities in human readable form box, it’s a little easier to understand what each capability does.
  • The tree structure in the left sidebar lets you quickly jump between core capabilities and capabilities added by plugins/custom post types.

For example, by jumping to the Forums custom post type, you could quickly edit the specific capabilities added by the bbPress forum plugin:

When you’re done, make sure to click the Update button. And that’s it! You just created a custom user role. If you go to create a new user or edit an existing user, you should see your new user role as an option:

How To Create A Custom User Role With Code

I think using User Role Editor is probably the easiest way for most people to create new roles and/or edit user capabilities. But it’s also fairly simple to do the same thing with code.

Let’s go through it…

Before we dig into the code, though, you need to know where to put it. You have three options:

Step 1: Create Your New Role

Ok, let’s start things off simple. To create a new role, this is all you need:

// Adds the WPLift Coder user role
$result = add_role(
'wplift_coder',
__( 'WPLift Coder' ),
array(
)
);

  • Replace wplift_coder with your own snippet. But keep it lowercase and don’t use spaces.
  • Replace WPLift Coder with the human name for your role

And right like that, your new role is active!

You can technically start assigning users that role. But – your new role doesn’t have any capabilities yet. It’s not very helpful without them, so you should probably fix that before you start using it!

Step 2: Assign New Capabilities To Your Role

To define the capabilities for your role, you use that empty array in the code example above.

By default, a new role has zero capabilities. That is, all capabilities return false. Therefore, to assign a capability to a role, you need to explicitly define it as true.

For example, let’s say that you want to create a user role that can:

  • View the dashboard
  • Upload files

You would assign it capabilities like so:

// Adds the WPLift Coder user role
$result = add_role(
'wplift_coder',
__( 'WPLift Coder' ),
array(
'read' => true,
'upload_files' => true,
)
);

So how would a user role with those capabilities look? Like this:

All it can do is view the basic dashboard, edit its profile, and upload media files.

If you want to give your role more power, all you need to do is add new capabilities using the same format. You can find a full list of core capabilities here.

Wrapping Things Up

Personally, I’m a fan of the User Role Editor plugin because it makes it much easier to see all the potential capabilities, including those added by plugins and custom post types.

But if you don’t want to add another plugin, using manual code isn’t too complicated – it can just be a bit tricky to keep track of capabilities if you’re creating a role that needs to be able to do lots of different things.

Finally – once you create your user roles, you should test them to make sure they’re working properly. To do that without wasting time, here’s a good way to switch between user roles on WordPress.

I hope you enjoyed the guide and let me know in the comments if you have any further questions!

Other interesting posts on WPLift

Colin Newcomer

Colin Newcomer

Colin Newcomer is a freelance writer and long-time Internet marketer. He specializes in digital marketing, WordPress and B2B writing. He lives a life of danger, riding a scooter through the chaos of Hanoi. You can also follow his travel blog.

4 thoughts on “How To Create Custom User Roles On WordPress (And Edit Capabilities)

  1. Sorry, but User Role Editor is far from perfect and has a limited functionality. I tried to work with it but deleted when I realized that I would not be able to customize the users roles on my site. I found the best plugin that offers paid features of User Role Editor absolutely free. Here is this plugin: https://wordpress.org/plugins/premmerce-user-roles/
    Its not promotion, I’m just shere my user experience.

  2. Hello there!
    I Rose who is certified in resolving all the technical errors as our Facebook customer service number is continually accessible 24*7 to rectify and clarify of some technical problems like how to create facebook business page or facebook password reset. Just dial our Facebook toll free number and avail quick services of our team which is full of highly trained experts.

Comments are closed.