Protect your sites from hackers and boost performance with Sucuri’s Junior Dev Security Bundle — now $500 off.

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:

  • Administrator: someone who has access to all the administrative features and functions within a site.
  • Editor: someone who can publish and manage posts of all users, including their own.
  • Author: someone who can publish and manage their own posts.
  • Contributor: someone who can write and manage their own posts but can’t publish them.
  • Subscriber: someone who can only manage their profile.

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:

  • add_role(): Enables you to add a custom role.
  • remove_role(): Enables you to remove a custom role.
  • add_cap(): Enables you to add a custom capability to a role.
  • remove_cap(): Enables you to remove a custom capability from a role.
  • get_role (): Gets information about a role as well as the capabilities associated with the role.

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:

  • Create posts
  • Edit posts
  • Edit Others posts
  • Manage categories
  • Edit Pages

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

  • Edit themes
  • Add or Remove Plugins
  • Update core

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 Avatar

45 responses

  1. Jurij from Latvia Avatar
    Jurij from Latvia

    I’m just testing this thing.

  2. Jurij from Latvia Avatar
    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!

  3. Patty J. Ayers Avatar
    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/.

  4. dicegeorge Avatar
    dicegeorge

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

  5. Zak Cagaros Avatar
    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.

  6. Frank Avatar
    Frank

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

  7. Luke Boobyer Avatar
    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.

  8. Anna Avatar
    Anna

    Good article….. thnx

  9. joe Avatar
    joe

    thank you for this post

  10. librianslover@gmail.com Avatar
    librianslover@gmail.com

    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

  11. Ron Avatar
    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!

  12. Abhay Udgire Avatar
    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 !

  13. Paal Joachim Romdahl Avatar
    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/

  14. Adson Avatar
    Adson

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

  15. Chris Avatar
    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?

  16. Dan Avatar
    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!

  17. Don Avatar
    Don

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

  18. Susan Avatar
    Susan

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

    Thanks

  19. Sherry Avatar
    Sherry

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

  20. Vuthy Avatar
    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 ?

  21. Shahzad Avatar
    Shahzad

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

  22. Kirk Avatar
    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

  23. reema Avatar
    reema

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

  24. Diana Hooper Avatar
    Diana Hooper

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

  25. tourvista Avatar
    tourvista

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

  26. Travis Avatar
    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.

  27. oi Avatar
    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’);

  28. tanya@wanaus.com.au Avatar
    tanya@wanaus.com.au

    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

  29. Jeremy Benson Avatar
    Jeremy Benson

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

  30. Craig Avatar
    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.

  31. Fran Avatar
    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?

  32. Rogier Koning Avatar
    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?

  33. Nenad Avatar
    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

  34. iqbal khan Avatar
    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

  35. Day Magtoto Avatar
    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)

  36. nesoor Avatar
    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?

  37. blackhawk Avatar
    blackhawk

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

Leave a Reply

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