How to Create Custom User Roles in WordPress

One of the key features in WordPress that is often overlooked is that there are a number of different user roles available. These user roles can  help make insure that only the people have access to just the areas they need and also helps minimize the chances of any  accidents happening that could potentially bring down the site. in this article we will look at those user roles briefly and also go into how to create your own custom roles.

User roles have been an important part of the WordPress experience since version 2.0. Most people don’t even know they exist and assign administrator rights to everyone who has access to their site dashboard (obviously not a good thing for a whole bunch of reasons). Off the shelf, WordPress comes with six default user roles:

Why Use Custom User Roles?

For the most part the default user roles are all that are needed. But there are cases where you need a user role that doesn’t fit in with the parameters of the default roles. And in this article I’ll show you how to create your own custom user roles without using a plugin.

Lets put a real world spin on why you would want to use Custom User roles. I typically use Custom User roles to make sure my clients only have access to what they need. I’m sure there are people who will debate that it is the client’s site and they should have admin access as the owner. And that’s fine if you don’t have a maintenance agreement with the client and are just handing the site over to the client and moving on to the next project.

But if you’re responsible for making sure the site stays up 24/7, then I recommend restricting the access of the client through a custom user role. That way I can give the client everything they need to make their site effective, like add content, maybe add events whatever they need to do. What they can’t do is things that can bring the site down or mess-up some functionality. I restrict things like access to add or remove plugins, themes, update core, all the kinds of things I’d want to do as part of my ongoing maintenance.

But lets start with a quick review of the basics, shall we?

Basic WordPress Functions

In order to manage roles and capabilities effectively, there are five very straightforward functions:

We are only going to use the add_role() function for this article as we are going to create a custom user role for our fictitious client.

Defining The User Role

So before we dive into the code we need to have a plan, because diving into code without a plan is never a good idea.

So we need to give the user role a name. We’ll keep it simple and call the user role ‘Client’.

So what can the user role ‘Client’ actually do? There are over 50 different capabilities available in a clean install of WordPress (the number increases once you start adding plugins, but we’ll go over that in another article). For our purposes we want the client to be able to do the following:

Equally important is what we don’t want them to be able to do:

Writing the Code

We are going to put this code into the functions.php file for our active theme. So lets start by adding this to the file:

// Add a custom user role

$result = add_role( 'client', __(
'Client' ),
array( ) );

By adding that piece of code, you have technically created a new user role (you can check it in the drop down on the Add New User page and it should be there). The problem is this user role has no functionality assigned to it. So the next step is obviously to add the functionality we had previously identified in our requirements above. Just add the array code to what you have already entered into your functions.php file.

// Add a custom user role

$result = add_role( 'client', __(

'Client' ),

array(

'read' => true, // true allows this capability
'edit_posts' => true, // Allows user to edit their own posts
'edit_pages' => true, // Allows user to edit pages
'edit_others_posts' => true, // Allows user to edit others posts not just their own
'create_posts' => true, // Allows user to create new posts
'manage_categories' => true, // Allows user to manage post categories
'publish_posts' => true, // Allows the user to publish, otherwise posts stays in draft mode

)

);

That will give us the functionality we want the client to have but we still need to restrict them from doing things that could potentially cripple the site. So lets add that now.

// Add a custom user role

$result = add_role( 'client', __(

'Client' ),

array(

'read' => true, // true allows this capability
'edit_posts' => true, // Allows user to edit their own posts
'edit_pages' => true, // Allows user to edit pages
'edit_others_posts' => true, // Allows user to edit others posts not just their own
'create_posts' => true, // Allows user to create new posts
'manage_categories' => true, // Allows user to manage post categories
'publish_posts' => true, // Allows the user to publish, otherwise posts stays in draft mode
'edit_themes' => false, // false denies this capability. User can’t edit your theme
'install_plugins' => false, // User cant add new plugins
'update_plugin' => false, // User can’t update any plugins
'update_core' => false // user cant perform core updates

)

);

How To Determine If The User Role Is Set Up Properly

WordPress SidebarMaking sure your new user role is working as intended requires you to set up a new user with the appropriate role, log out and log back in as the new user.

Depending on what capabilities you’ve allowed and what you have denied, the first thing you should notice is a change in what’s available in the dashboard. The image below shows you what you would see if you set up the client role as we did above.

As you can see, the options available to this user are greatly reduced as a result of what has been allowed and what has explicitly been denied. You now have some piece of mind as a developer/site manager that you  hopefully won’t be getting that call saying “I don’t know what happened, but all of a sudden my site isn’t there.”

Al Davis

45 Comments

  1. blackhawk

    How can we also include the option to uninstall a plugin to this given list?

  2. nesoor

    Hey, I added the exact code in my functions.php and it is working but the Role “client” does not have access to the dashboard. Any idea why it might not work?

    1. ahsan ion

      make all true

  3. Day Magtoto

    what if i just want to protect one page? I don’t want my fellow administrator to touch it (if there are two admins)

  4. iqbal khan

    Good article in the starting. I want to make a custom role for my contributers, where they would not be able to see other users post.
    But at end coding eats me up…. and was not able to understand a single thing.
    Can u suggest me to make it simple with some widgets

  5. Nenad

    How are you creating a custom user role on all subsites in multisite. The code above does it only on the main site in a multisite installation.

    Thanks

  6. Rogier Koning

    We would like to create a new user role with some extra fields when they subscribe. We want to have a role called Patients and next to their name, email and password we also would like to have Date of Brith, weight, gender or things like that. Is this also possible?

  7. Fran

    Great article!

    I am very new into WP developing, and I qould like to ask: is there a way to allow custom roles to edit already created pages but not adding new ones?

  8. Craig

    I found this post because I already use ManageWP, and we have custom user roles — the same ones — on every site we build and/or manage. It is mission critical for us to be able to add and manage users across multiple websites that have a user role other than the five default WordPress roles. This is so critical that failing some feature addition by ManageWP to include this capability, we’ve started to look for an alternative solution to replace ManageWP. This would make us sad as we’ve been very happy during our first few weeks of testing, but this is borderline deal-killer with out.

    1. Nemanja Aleksic

      Hi Craig,

      Have you considered using Code Snippets for custom user roles?

      It’s not an ideal solution, but it’s the best we can do for now, because there’s very little interest in such a feature.

  9. Jeremy Benson

    Users with custom user role aren’t displaying in the ManageWP Dashboard, is there a trick to getting them to display?

    1. Nemanja Aleksic

      Custom roles are currently not supported. We have plans to support them in the future, but only on the single website level.

  10. tanya

    I’m not sure if this post is still current but I have one client so no need to invest just yet. The code you provide is fabulous. I just need to give the client access to some functions of an event plugin, like create event, edit event, etc. I added event to the line that said posts but that didn’t work. Do you have any ideas? The
    I am only creating the website for them and I am not going to have much input however they know little about running a website.
    I will help from time to time but the code you have given will give them enough functionality for the time being.
    They also need to upload photos.

    Many thanks for your help in advance
    Tanzi

  11. oi

    Is there a capability for the action to receive an automatic email about a new user awaiting approval?
    I have already give the Editor role capability to approve users :
    $edit_editor->add_cap(‘edit_users’);
    $edit_editor->add_cap(‘list_users’);
    $edit_editor->add_cap(‘promote_users’);
    $edit_editor->add_cap(‘create_users’);
    $edit_editor->add_cap(‘add_users’);
    $edit_editor->add_cap(‘delete_users’);

  12. Travis

    Not working !!
    When I write
    ‘read’ => true, // true allows this capability
    ‘create_posts’ => true, // Allows user to create new posts
    ‘edit_posts’ => false,
    ‘delete_posts’ => false,

    the custom user is not able to post ” new” post. (their is no option/button for New Post)
    I just want my custom user to write new post and after submitting for review he should NOT be able to edit and delete his post.

  13. tourvista

    Awesome, great tutorial and explanation on a pretty intimidating subject. Just another example on why WordPress is such a great platform.

  14. Diana Hooper

    Thank you for sharing this information – it is exactly what I needed! 🙂

  15. reema

    we add a new role in our site but that’s role invalid registration .

  16. Kirk

    (10 Can a new role be limited as to which category it can post to? And,

    (2) Can the new role be set so it can use one plugin, and one plugin only?

    Thanks

  17. Shahzad

    i want to add role for only single post , not multi?
    how can i add?

  18. Vuthy

    Hello sir, if i have want to limit post for user( Example. Normal user can post only 6 items). So how can i do ?

  19. Sherry

    Is there a way to call a css for each custom role?

  20. Susan

    What can I add to give the user access to the plugins?

    Thanks

  21. Don

    So, will this code need to be rewritten every time the theme is updated?

    1. Aaron

      If you are using a third party theme then you will most likely need to do re add the code when the theme updates. You can easily add the same functionality to your site via a custom plugin 🙂

      https://codex.wordpress.org/Function_Reference/add_role
      The last example there is for the plugin

  22. Dan

    Where can one find a listing of all the reference codes for each user’s coded abilities? i.e. ” ‘read’ => true, ”

    I’m specifically looking to enable ‘users’ and disabling ‘jetpack’.

    Thanks for anyone’s input, and thanks to Al for the great article!

  23. Chris

    This is weird. The code works just fine in a single-site install on localhost, but doesn’t seem to work in multisite. Maybe there’s more to a WPMU install than I realize?

  24. Adson

    How to display an select field for custor user roles in registration form??

    1. Brandon

      There’s a plugin available called ‘WP roles at registration’. It hasn’t been updated in 2 years but it still works fine. It will implement a drop-down box on your registration page. In the plugin settings you will be able to select which roles to include in this drop-down. I’ve been using it for some time now and it has worked great.

  25. Paal Joachim Romdahl

    I am working on a tutorial for:
    – Reordering the left admin menu.
    – Removing left admin menu items from top and submenu.
    – Tying it all together into a custom role, but am noticing the custom roles use different kinds of code then the above making it a bit more tricky. How would I go about using code from the above with a custom role? Here is the article I am working on…
    http://easywebdesigntutorials.com/reorder-left-admin-menu-and-add-a-custom-user-role/

  26. Abhay Udgire

    first of all thank you for this post it was really helpful to start with custom user type in wordpress. But I want to use new registration form in my website and add the role of custom created user to that registration how can I achieve this ? any help will be appreciated. thank you !

    1. Brandon

      Look for ‘WP Roles at Registration’ plugin. It hasn’t been updated in some time but it still works fine.

  27. Ron

    Hi, how can I make wordpress users manage only their posts. So “User A” can only manage/view “User A Posts”. No other users can see his/her post except for the admin ofcourse.

    Thanks!

    1. Chris

      Add this to your add_role function in the array portion:

      ‘edit_others_posts’ => false

  28. librianslover

    Hi, Thank you very much for this article. I have one query, i followed steps one by one but when i log-in with new role account i get this message: You do not have sufficient permissions to access this page. Can you please guide me for this.

    Thanks

    KR

  29. joe

    thank you for this post

  30. Anna

    Good article….. thnx

  31. Luke Boobyer

    Great little tutorial. I’ve recently been experimenting with creating different user roles for a couple of projects I’m working on. There are plugins around that make it easy for you but there’s nothing better than actually doing it yourself.

  32. Frank

    Great post, Hire Dedicated Part time, Full time wordpress developers for wordpress theme/template or plugin/widget development.
    Thanks for sharing this post.

  33. Zak Cagaros

    Excellent article – makes coding look like a piece of cake! This is something that will be extremely useful in a situation where you have client that wants to add someone to their team but only give them access to what they need. Just one correction; unless I’ve missed something, there are 5 default user roles in WordPress not 6 as you mentioned.

  34. dicegeorge

    you wrote:
    “You now have some piece of mind”
    which spellchecked ok but
    peace of mind!

  35. Patty J. Ayers

    Good information. If, like me, you’re not a strong coder, there’s a plugin for this which has been working well for me for about a year now: User Role Editor – https://wordpress.org/plugins/user-role-editor/.

  36. Jurij from Latvia

    Good write up, Al. Very timely too. I was just deciding which role to assign to all the guest bloggers. Keep it up!

  37. Jurij from Latvia

    I’m just testing this thing.

Leave a Reply

Your email address will not be published. Required fields are marked *

Over 65,000 WordPress professionals are already using ManageWP

Add as many websites as you want for free, no credit card required. Sign up and start saving time!

Have questions? Get in touch!

Over 65,000 WordPress professionals are already using ManageWP

Add as many websites as you want for free, no credit card required. Sign up and start saving time!



Have questions? Get in touch!

Over 65,000 WordPress professionals are already using ManageWP

Add as many websites as you want for free, no credit card required. Sign up and start saving time!



Have questions? Get in touch!

Over 65,000 WordPress professionals are already using ManageWP

Add as many websites as you want for free, no credit card required. Sign up and start saving time!



Have questions? Get in touch!