Plugins Plugin hub Backup SEO Caching Security Forms WooCommerce Images Best backup plugins
Hosting Hosting directory Shared hosting Managed WordPress Cloud hosting VPS hosting By reader location Hosting finder
Themes & builders Compare Rank Math vs Yoast
Tools All tools Hosting finder Plugin stack builder Cost calculator Salt generator Theme detector Who is hosting this? Speed test Headline analyzer robots.txt generator Redirect generator Uptime calculator Blog name generator
Blog Best backup plugins Deals
Guides All guides Speed up WordPress Choose hosting Back up WordPress
How we test

Developer · Guide

How to Add Custom User Roles and Capabilities

How to Add Custom User Roles and Capabilities

Short answer

To add a custom user role in WordPress, call add_role() on the init hook with a slug, a display name, and the capabilities the role needs, inside a plugin. Add a capability to an existing role with get_role() and add_cap(), run the code on plugin activation only, and check the role by logging in as a user who has it.

Key takeaways

  • WordPress ships with six default roles, from Super Admin to Subscriber.
  • Roles and their capabilities are stored in the options table under user_roles.
  • add_role() stores a role on the first call, and repeat calls change nothing.
  • Give a new role only the capabilities its tasks need, and always include read.
  • edit_theme_options is the main capability a Site Editor role needs.
  • Run role code on plugin activation, not on every page load.

What is a user role in WordPress?

A user role is a named set of capabilities that decides what one user may see and do in the WordPress dashboard.

Roles and capabilities are two parts of one system. The Plugin Handbook states that roles and capabilities are two important aspects of WordPress that allow you to control user privileges. Roles and Capabilities is the handbook chapter that covers the system (checked November 2026).

A role is the label, and a capability is one permission inside it. A role defines a set of capabilities for a user, such as what the user may see and do in the dashboard. Roles and Capabilities states that plainly (checked November 2026).

WordPress stores the roles and their capabilities in the options table under the user_roles key. Roles and Capabilities states that storage fact (checked November 2026).

Learn WordPress states the same storage in more depth: the roles are stored as a serialised array in the user_roles option, and on a single site install with the default table prefix the option is wp_user_roles.

Developing with user roles and capabilities covers the storage and the checks (checked November 2026).

Every time a logged-in user tries an action, WordPress checks the user role capabilities with the current_user_can() function. Developing with user roles and capabilities states that if the user has the capability, the action is allowed, and if not, it is denied (checked November 2026).

What are the six default roles and what can each do?

WordPress ships with six default roles, from Super Admin down to Subscriber, and each one carries a set of capabilities.

The Plugin Handbook lists the six as Super Admin, Administrator, Editor, Author, Contributor, and Subscriber, and notes that more roles can be added and the default roles can be removed. Roles and Capabilities gives that list (checked November 2026).

WordPress.org describes each role in plain words.

The Administrator has access to all the administration features within a single site, the Editor can publish and manage posts including the posts of other users, and the Author can publish and manage their own posts. Roles and Capabilities gives those short role summaries (checked November 2026).

The same page states that the Contributor can write and manage their own posts but cannot publish them, and the Subscriber can only manage their profile (checked November 2026). The Super Admin is the one role that exists only on a multisite install, where it can manage the whole network.

The Subscriber role is the smallest. Roles and Capabilities states that the Subscriber role has just the “read” capability (checked November 2026). That single capability lets the user log in and see the dashboard, and nothing more.

When a new user is created in the WordPress dashboard, they are assigned the Subscriber role by default. Developing with user roles and capabilities states that you can change this by assigning a different role (checked November 2026).

You can also set the default role for new users in the dashboard. Roles and Capabilities states that the default role for new users can be set in Administration Screens, then Settings, then General (checked November 2026).

RoleWhat the user can doTypical use
Super AdminManage the whole multisite networkNetwork owner only
AdministratorManage all features of one siteSite owner
EditorPublish and manage all posts and pagesContent lead
AuthorPublish and manage their own postsRegular writer
ContributorWrite posts, but not publish themGuest writer
SubscriberRead the site and manage their profileMember or customer

What do you need before you add a custom role?

You need an administrator account, a clear list of tasks the new role must do, and a small plugin to hold the code.

List the tasks first, then pick the smallest set of capabilities that covers them. A role that only needs to manage plugins should get activate_plugins and update_plugins, not full admin rights.

Decide the role slug and the display name now. The slug is a lowercase name with no spaces, such as simple_role, and the display name is the label shown in the dashboard, such as “Simple Role”.

Use a plugin for the code, not the theme. Role data lives in the database, so the role stays even if you change themes, but the code that creates it should live where it is easy to find and remove.

Allow 30 to 60 minutes for a first custom role, including a login check as the new user. The code itself is short, and most of the time goes to checking what the role can and cannot do.

A guide on how to stop fake user registrations in WordPress is worth reading before you open registration to new roles, since open registration plus a wide default role can let strangers in.

How do you add a custom role with code?

Add the role with add_role() on the init hook, inside a plugin, and WordPress stores it in the database on the first call.

The Plugin Handbook states that you add new roles and assign capabilities to them with add_role(). Roles and Capabilities gives this example (checked November 2026):

function wporg_simple_role() {
    add_role(
        'simple_role',
        'Simple Role',
        array(
            'read'         => true,
            'edit_posts'   => true,
            'upload_files' => true,
        ),
    );
}
add_action( 'init', 'wporg_simple_role' );

The three arguments are the role slug, the display name, and the array of capabilities. Each capability is a key set to true when the role should have it.

The handbook states that after the first call to add_role(), the role and its capabilities will be stored in the database. Roles and Capabilities adds that sequential calls will do nothing, including altering the capabilities list (checked November 2026).

To change the capabilities of a role you already added, remove the role with remove_role() and add it again with add_role() and the new list. Roles and Capabilities states that bulk change rule (checked November 2026).

Do not run the role code on every page load. Learn WordPress states that because the new role will be stored in the database, you should only run this code when the plugin is activated, and not on every page load. Developing with user roles and capabilities gives that warning (checked November 2026).

Use register_activation_hook() to run the code once, when the plugin is switched on. That keeps the database write to one moment instead of repeating it on each request.

How do you add a capability to an existing role?

Get the role object with get_role() and call add_cap() on it to add one capability at a time.

The Plugin Handbook states that you use get_role() to get the role object, then use the add_cap() method of that object to add a new capability. Roles and Capabilities gives this example (checked November 2026):

function wporg_simple_role_caps() {
    $role = get_role( 'simple_role' );
    $role->add_cap( 'edit_others_posts', true );
}
add_action( 'init', 'wporg_simple_role_caps', 11 );

The priority of 11 matters here. The handbook notes that the priority must be after the initial role definition, so the role exists before the capability is added.

A common case is giving Editors the right to manage plugins. By default, the Editor role does not have the activate_plugins or update_plugins capability. Developing with user roles and capabilities states that gap, and shows adding both capabilities on plugin activation (checked November 2026).

Learn WordPress adds a warning that fits here: because adding capabilities to a role is a permanent change, you should only do this when the plugin is activated, and not on every page load. Developing with user roles and capabilities states that rule (checked November 2026).

You can also add a custom capability of your own, with any name you choose. The handbook states that it is possible to add custom capabilities to any role.

Under the default WordPress admin they would have no effect, but they can be used for custom admin screens and front-end areas. Roles and Capabilities states that (checked November 2026).

To take a capability away, use remove_cap() on the same role object. The handbook states that the steps match adding a capability, with remove_cap() in place of add_cap() (checked November 2026).

How do you give a custom role access to the Site Editor?

Give the role edit_theme_options, plus the editing and reading capabilities the Site Editor needs to load and save.

WordPress.org states that edit_theme_options is the primary capability WordPress checks when it decides whether a user can access and manage templates through the Site Editor. Roles and Capabilities gives that rule (checked November 2026).

The same page lists the other capabilities a Site Editor role may need: edit_posts for managing templates, edit_pages for page templates, edit_others_posts for managing templates, read for previewing changes, and upload_files for adding images and media. Roles and Capabilities lists them in a table (checked November 2026).

WordPress.org gives a full example role for this job, a “Site Editor” role with read, edit_theme_options, edit_posts, edit_pages, edit_others_posts, and upload_files all set to true. Roles and Capabilities shows that example (checked November 2026).

Note the warning on that page: when adding capabilities to an existing role, consider the wider permissions each capability grants. Roles and Capabilities states that edit_theme_options is not limited only to the Site Editor and may grant access to other theme-related admin functions (checked November 2026).

If a custom role can open the Site Editor but some sections fail to load or save, check the browser developer tools for REST API requests that return 401 Unauthorized or 403 Forbidden.

Roles and Capabilities states that the response will often include an error code that points to the missing capability (checked November 2026).

A guide on fixing the REST API error in Site Health covers the checks that confirm the API itself is answering before you blame the role.

How do you check that a role works and remove it when done?

Create a user with the new role, log in as that user, and confirm each task works before you hand the role to anyone.

Create the user from Users, then Add User, and pick the new role in the Role list. Log out, log in as that user, and walk through each task the role must do, such as editing a post, uploading a file, or opening the Site Editor.

Check the menu as well as the task.

Learn WordPress states that the read capability is required for a user with a role to access the dashboard, and that regardless of any other capabilities a user has, without read they cannot reach the Dashboard menu. Developing with user roles and capabilities states that rule (checked November 2026).

Use current_user_can() in your own code to gate a feature behind a capability.

The handbook states that current_user_can() is a wrapper for user_can() that uses the current user object. Roles and Capabilities gives an example that shows an Edit link only when the user can edit posts (checked November 2026).

if ( current_user_can( 'edit_posts' ) ) {
    echo 'You can edit posts.';
}

The check itself is the point: the message only shows for a user whose role holds edit_posts.

Keep a log of what each role can do. A guide on how to audit user activity in WordPress shows how to watch what users with a new role actually do on the site.

To remove a custom role, use remove_role() on plugin deactivation.

Learn WordPress states that it is a good idea to remove a custom role on deactivation with register_deactivation_hook(), so the change is cleaned up if the plugin is switched off. Developing with user roles and capabilities states that cleanup step (checked November 2026).

What mistakes should you avoid?

Avoid giving admin-level capabilities to a custom role, running role code on every page load, and deleting roles without a plan.

Do not hand out install_plugins, edit_users, manage_options, or update_core to a role that only needs to edit content. Each of those opens a wide door, and the role keeps it until you take the capability away.

Do not run add_role() or add_cap() on every request. The handbook warns that you should condition the change or you will degrade performance considerably. Roles and Capabilities states that warning next to the remove-and-re-add rule (checked November 2026).

Do not delete the Administrator role. The handbook advises against removing the Administrator and Super Admin roles, and notes that future WordPress updates may add the default roles again. Roles and Capabilities states that advice (checked November 2026).

Do not assume a role is safe because its name sounds small. Check the capability list in the database or in code, and log in as a user with that role to see the menus and screens it can reach.

Frequently asked questions

Does a custom role disappear when I remove the code?

No. WordPress stores the role and its capabilities in the database on the first add_role() call, so the role stays even if the code is removed. Use remove_role() on plugin deactivation to clean it up, or the role will stay in the database.

Which capabilities should a custom role always have?

Give it only the capabilities that match its tasks, and always include read, since a user without read cannot open the dashboard. Never hand out install_plugins, edit_users, or manage_options to a role that only needs to edit content.

Can I change a role by calling add_role() again?

No. add_role() does nothing on repeat calls, including changing the capability list. To change the list, remove the role with remove_role() and add it again with add_role() and the new capabilities, or change single capabilities with add_cap() and remove_cap().

Can a custom role use the Site Editor?

Yes, if the role holds the right capabilities. The main one is edit_theme_options, plus edit_posts, edit_pages, edit_others_posts, read, and upload_files. Without edit_theme_options, template endpoints return an authorization error.

How do I add one capability to the Editor role?

Yes. Use get_role() to fetch the role object, then call add_cap() with the capability name and true. Run that code on plugin activation, not on every page load, since the change is written to the database at once.

How do I check a new role before giving it to anyone?

Create a user with the new role, log out, and log in as that user. Walk through each task the role must do, such as editing a post or opening the Site Editor, and check the menus. Also check that tasks outside the role are blocked.

Sources

  1. Roles and Capabilities WordPress Developer Resources
  2. Roles and Capabilities WordPress.org
  3. Developing with user roles and capabilities Learn WordPress
  4. Miscellaneous developer changes in WordPress 6.3 Make WordPress Core

Is your product missing, or something out of date?

Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.

About the editors

WPLegible editors

Researched from the primary sources listed above and checked against our editorial rules. About the site · How we test