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
Making 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.”
blackhawk
How can we also include the option to uninstall a plugin to this given list?
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?
ahsan ion
make all true
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)
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
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
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?
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?
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.
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.
Jeremy Benson
Users with custom user role aren’t displaying in the ManageWP Dashboard, is there a trick to getting them to display?
Nemanja Aleksic
Custom roles are currently not supported. We have plans to support them in the future, but only on the single website level.
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
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’);
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.
tourvista
Awesome, great tutorial and explanation on a pretty intimidating subject. Just another example on why WordPress is such a great platform.
Diana Hooper
Thank you for sharing this information – it is exactly what I needed! 🙂
reema
we add a new role in our site but that’s role invalid registration .
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
Shahzad
i want to add role for only single post , not multi?
how can i add?
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 ?
Sherry
Is there a way to call a css for each custom role?
Susan
What can I add to give the user access to the plugins?
Thanks
Don
So, will this code need to be rewritten every time the theme is updated?
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
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!
Shane
https://codex.wordpress.org/Roles_and_Capabilities
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?
Adson
How to display an select field for custor user roles in registration form??
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.
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/
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 !
Brandon
Look for ‘WP Roles at Registration’ plugin. It hasn’t been updated in some time but it still works fine.
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!
Chris
Add this to your add_role function in the array portion:
‘edit_others_posts’ => false
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
joe
thank you for this post
Anna
Good article….. thnx
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.
Frank
Great post, Hire Dedicated Part time, Full time wordpress developers for wordpress theme/template or plugin/widget development.
Thanks for sharing this post.
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.
dicegeorge
you wrote:
“You now have some piece of mind”
which spellchecked ok but
peace of mind!
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/.
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!
Jurij from Latvia
I’m just testing this thing.