keepcalculator

06 Numbers and Powers

Create Custom WordPress User Roles: Full Guide

Card No. 06·71937 · Updated · Standard formula, shown below

Yes, you can create custom WordPress user roles without writing code by using a plugin, or with code by adding a function to your theme’s functions.php file. This article explains both methods, what custom roles can do, and how to choose the right approach for your site.

What Are WordPress User Roles?

WordPress comes with six default roles: Super Admin, Administrator, Editor, Author, Contributor, and Subscriber. Each role has a set of capabilities—specific actions a user is allowed to perform, such as editing posts, moderating comments, or installing plugins. The default roles work for many sites, but they are often too broad or too narrow. For example, an Editor can edit all posts, but you might want a user who can only edit posts in a certain category. That is where custom roles come in.

Why Create a Custom User Role?

Custom roles let you match permissions to real job duties. Common reasons include:

  • Giving a client access to only their own portfolio pages.
  • Letting a freelance writer submit drafts without seeing other users’ content.
  • Allowing a support agent to manage customer orders but not change site settings.
  • Restricting plugin or theme updates to a single administrator.

Without custom roles, you either give too much access (a security risk) or too little (users get locked out of what they need). Custom roles solve that by letting you define exactly what each user can and cannot do.

Method 1: Using a Plugin (No Code)

For most site owners, a plugin is the easiest and safest route. Popular plugins like User Role Editor, Members, and Capability Manager Enhanced provide a graphical interface to create roles and tick capabilities. Here’s the general process:

  1. Install and activate a role management plugin from the WordPress repository.
  2. Go to the plugin’s settings page (often under Users or a new menu item).
  3. Click “Add Role” and give it a name (e.g., “Shop Manager”).
  4. Select the capabilities you want to grant. You can start from scratch or copy an existing role.
  5. Save the role, then assign it to users from the user edit screen.

Plugins also let you edit existing roles—for example, removing the “delete_posts” capability from Authors. Most plugins store changes in the database, so they are reversible if you keep a backup.

Method 2: Adding Code to functions.php

If you prefer code, you can add a function to your child theme’s functions.php file. The function uses add_role() and add_cap(). Here is a minimal example for a “Moderator” role that can moderate comments but not edit posts:

function add_moderator_role() {
    add_role( 'moderator', 'Moderator', array(
        'moderate_comments' => true,
        'read' => true,
    ) );
}
add_action( 'init', 'add_moderator_role' );

To add capabilities to an existing role, use get_role() and add_cap():

function add_caps_to_editor() {
    $role = get_role( 'editor' );
    $role->add_cap( 'edit_theme_options' );
}
add_action( 'init', 'add_caps_to_editor' );

Important: Never edit the functions.php of a parent theme directly, because updates will erase your changes. Use a child theme or a site-specific plugin. Also, if you remove the code later, the role will remain in the database—you must delete it manually.

How to Choose Between Plugin and Code

Your choice depends on your comfort level and how many roles you need.

  • Plugin: Best for non-developers, quick changes, and visual feedback. It also handles role deletion and capability search. The downside is that some plugins add database overhead, and you rely on third-party updates.
  • Code: Best for developers who want full control, no extra plugin weight, and the ability to version-control roles with the theme. The downside is that mistakes can lock users out or expose sensitive capabilities.

If you only need one or two simple roles, code is fine. If you manage many clients or complex permission sets, a plugin saves time.

Common Problems and How to Avoid Them

Creating custom roles is straightforward, but a few pitfalls can bite you:

  • Locking yourself out: If you remove the administrator role or its capabilities, you may lose access. Always keep a backup and test with a secondary admin account.
  • Capability names misspelled: A single typo means the capability won’t work. Use the official WordPress capability list.
  • Not using a child theme: If you add code to the parent theme, an update will wipe your roles. Use a child theme or a site-specific plugin.
  • Overlapping roles: If a user has multiple roles, they get the union of capabilities. That can accidentally grant more access than intended. Check each user’s role assignments.
  • Plugin conflicts: Some plugins add their own capabilities (e.g., WooCommerce adds “manage_woocommerce”). If you copy an existing role, you may miss these custom capabilities. Use a plugin that shows all capabilities, including those added by other plugins.

If a user complains they can’t do something, first check whether the capability is actually assigned. Use a plugin like “User Role Editor” to search for the capability name.

Costs and Safety Considerations

Most role management plugins are free in the WordPress repository. Premium versions may offer advanced features like content restrictions or role cloning, but the free versions are sufficient for most needs. There is no ongoing cost unless you choose a paid plugin or hire a developer.

Safety-wise, custom roles are only as safe as the capabilities you grant. The biggest risk is giving a non-admin the unfiltered_html capability, which lets them post raw HTML and JavaScript—a dangerous XSS vector. Similarly, avoid granting activate_plugins or edit_theme_options to anyone you don’t fully trust. Always follow the principle of least privilege: give users only the capabilities they need for their job.

Also, when you delete a role, users assigned to that role are not deleted—they just lose all capabilities. Make sure to reassign them to another role first.

Alternatives to Custom Roles

If custom roles feel like overkill, consider these alternatives:

  • Plugins that add their own roles: Many e-commerce and membership plugins (e.g., WooCommerce, LearnDash) create their own roles with pre-set capabilities. You may not need to build anything.
  • Capability plugins with conditional logic: Some plugins like “Members” allow you to conditionally grant capabilities based on user meta or context, without creating a separate role.
  • User groups: If you only need to control which posts a user sees, a content restriction plugin might be simpler than role management.
  • Multisite: On a WordPress Multisite network, you can use Super Admin vs. regular admins instead of custom roles for site-level control.

Custom roles are the right tool when you need a distinct set of capabilities that doesn’t exist in any default role. For one-off restrictions, a plugin or a simple capability tweak may be enough.

Frequently Asked Questions

Can I create custom roles without a plugin?

Yes, you can add code to your theme’s functions.php or create a small custom plugin. The add_role() function is built into WordPress. However, if you are not comfortable editing code, a plugin is safer.

Will custom roles break when I update WordPress?

No, custom roles are stored in the database and survive WordPress updates. However, if you added the role via code in a parent theme, a theme update will remove the code that created it, but the role will still exist in the database—it just won’t be re-created if you delete it.

How do I delete a custom role?

You can delete a role via a plugin like User Role Editor, or with code using remove_role( 'role_slug' ). Before deleting, reassign any users who have that role to another role, otherwise they will lose all capabilities.

Can I give a custom role access to only certain pages?

Yes, but that requires more than just role creation. You need a plugin that restricts content by role (e.g., “Members” or “Restrict Content”). The role defines capabilities, and the content restriction plugin determines which posts or pages each role can view.

What’s the difference between a role and a capability?

A role is a named collection of capabilities. A capability is a specific permission, like edit_posts or moderate_comments. Users are assigned roles, and roles grant capabilities. You can also assign capabilities directly to a user, but that is less common.

Is it safe to give a custom role the unfiltered_html capability?

No. This capability allows users to post raw HTML and JavaScript, which can lead to cross-site scripting (XSS) attacks. Only give it to administrators or users you trust completely. In most cases, you should never grant it to custom roles.

Related

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.

More cards in this drawer

The whole Numbers and Powers drawer →