The standard roles almost fit. Your office manager needs to update the menu, but the Editor role cannot touch menus and Administrator would let her delete plugins. Or a junior staff member should be able to edit service pages but never delete one. Or a guest writer should be able to add photos to drafts without being able to publish. Each time, the choice seems to be “too little” or “far too much”.
A custom user role in WordPress fills that gap. You decide exactly which permissions a role has, give it a clear name, and assign it to the people who need it. You need a plugin for it, and most of the effort goes into testing the role rather than creating it.
Start with the built-in roles
Before building anything, be sure the standard roles really do not work. Many owners create custom roles for jobs that Editor or Author already covers. Our guide to what the standard WordPress roles allow sets out each one. A custom role is worth it when you can name a specific permission the person needs and a standard role lacks, or a specific power a standard role has that you want to take away.
Capabilities, in plain words
WordPress roles are built from capabilities: small, named permissions, each switching one ability on. A role is simply a list of them. Role editor plugins show these by their internal names, so it helps to know what the common ones mean.
| Capability | What it allows |
|---|---|
| read | Entering the dashboard at all. Every role needs it. |
| edit_posts, publish_posts | Writing posts and publishing them |
| edit_others_posts, edit_others_pages | Editing content that someone else wrote |
| edit_pages, edit_published_pages | Working on pages, including ones already live |
| delete_pages, delete_published_pages, delete_posts | Moving content to the Trash |
| upload_files | Adding images and documents to the Media Library |
| moderate_comments | Approving, editing and removing comments |
| manage_categories | Creating and renaming categories and tags |
| edit_theme_options | Menus, widgets, the Customizer and the Site Editor |
| list_users, create_users, edit_users | Seeing, adding and changing user accounts |
| activate_plugins, install_plugins | Switching plugins on and off, and adding new ones |
| manage_options | The Settings menu and many plugin settings screens |
Plugins add their own capabilities too, for things like viewing form entries, managing shop orders or editing SEO settings. Role editor plugins list those as well, usually grouped by the plugin that created them.
Choosing a plugin
WordPress has no screen for editing roles, so you need a plugin. Two long-standing ones are Members and User Role Editor. Both let you create a new role, often by copying an existing one as a starting point, and tick or untick capabilities. Pick one and stay with it; running two role editors side by side invites confusion.
Know one important behaviour before you start. Roles are saved in your site’s database, not inside the plugin. Changes you make generally stay in place even if you later deactivate or delete the plugin. So removing the plugin does not undo your work. If you want a role gone, delete it inside the plugin before you uninstall.
How to create a custom user role in WordPress
The screens differ slightly between plugins, but the steps are the same.
- Take a backup, or better still try this on a staging copy of the site first.
- Install and activate one role editor plugin. Each adds its own screen for roles; where it appears in the menu depends on the plugin and its version, and the plugin’s description will tell you.
- Create a new role by copying the closest built-in one. Starting from Editor and removing two capabilities is much safer than starting from nothing and adding thirty.
- Give it a clear name that describes the job, such as “Content Manager” or “Comment Moderator”. You will see this name in the role dropdown when assigning people.
- Adjust the capabilities. Change as few as possible to get the result you need.
- Save the role.
- Assign it by editing a user and choosing the new role from the Role dropdown.
Three common examples
An Editor who can also manage menus
Copy Editor and add edit_theme_options. Be aware this capability is broader than its job suggests. On a classic theme it opens Menus, Widgets and the Customizer. On a block theme it opens the Site Editor (Appearance → Editor), where the person can change headers, footers, templates and global styles for the whole site. That may be fine for a trusted manager. It is not a small permission.
A page editor who cannot delete
Copy Editor and remove the delete capabilities for pages and posts: delete_pages, delete_published_pages, delete_others_pages, and the matching ones for posts. The person can still change any page, so mistakes are possible, but revisions let you restore an earlier version. Nothing can vanish into the Trash by accident.
A guest writer who can add images
Contributors write posts that someone else approves, which suits guest writers well, but they cannot upload files. That means every image has to be sent to you separately. Copy Contributor and add upload_files. The writer can now place images in their drafts, while publishing still needs your approval. They will also be able to see the Media Library, so keep anything private out of it.
Testing the role as that person would see it
Ticks on a settings screen do not tell you what the person will actually see, so log in as them and look.
- Create a test account with the new role and its own email address.
- Log in as that account in a private browser window, keeping your administrator session open in the normal window.
- Look at the left menu. Is everything they need there? Is anything there that should not be?
- Try the actions you meant to block, such as deleting a page. The option should be missing or refused.
- Try the actions they need, all the way through, including saving and publishing.
- Delete the test account when you are satisfied.
A plugin such as User Switching lets an administrator jump into another account and back without logging out, which makes testing quicker. Remove it when you are done if you do not need it day to day.
Mistakes that cause real trouble
- Editing the Administrator role. Removing capabilities from it can lock you out of your own settings. Leave it alone.
- Changing a built-in role instead of making a new one. Every user with that role changes at once, and other people will expect “Editor” to mean the standard Editor.
- Removing “read”. Without it, users with that role cannot enter the dashboard at all.
- Giving user-management powers casually. A role that can edit users can often raise its own role or create administrators. Keep create_users, edit_users and promote_users for administrators.
- Not writing it down. Note what each custom role is for and what you changed. The next person to look after the site will need it.
If you want a record of what people with these roles do, an activity log helps, and that is covered in seeing who changed what in WordPress. Roles are one part of the user picture; the rest is in the hub on managing WordPress accounts. For everything else involved in managing your WordPress site, from settings to updates, the main guide is the place to start.
Frequently asked questions
Will a custom role survive WordPress updates?
Yes. Roles live in your site’s database, and core updates do not reset them. Plugin updates can occasionally add new capabilities that your custom role does not have, so if a feature stops appearing for those users after an update, check whether the plugin added a new permission that needs ticking.
Can one user have two roles?
WordPress itself allows it, but the standard profile screen only shows one role dropdown. Some role editor plugins add a way to assign more than one. In most small business cases a single custom role with the exact capabilities is easier to understand than two roles stacked together.
How do I remove a custom role I no longer need?
First move everyone who has that role to another one, otherwise they may be left without a role. Then delete the role in the same plugin you used to create it. Do this before uninstalling the plugin, because uninstalling usually leaves the role in the database.
Can a custom role limit someone to specific pages only?
Not with capabilities alone. Capabilities control types of action, such as editing pages in general, not individual pages. Restricting a person to chosen pages needs a plugin built for content permissions, and it is worth testing such plugins carefully on a copy of the site first.
A role that is slightly wrong tends to show up weeks later, when someone hits a screen they cannot open. Our WordPress support team can build and test a role for a particular person on a copy of the site, then apply it to the live site after a backup.
Next in this series: How to Log Out All Sessions in WordPress
