Introduction

Managing who can do what on your WordPress site is one of the first things you as a site owner shoud learn. WordPress comes with a role‑capability system that lets you control everything from content creation to plugin installation. Getting it right means users have just enough access to do their jobs, and not enough to break or compromise your precious website.

This guide walks through the built‑in roles, how the capability system works, when and how to create custom roles, and the safest ways to make changes both using plugins or code.

Built‑in Roles (single‑site)

WordPress ships with five default roles. Each role is a bundle of capabilities; you rarely need to assign individual capabilities to a user.

Note — WordPress Multisite adds a Super Admin role with network‑wide capabilities (manage networks, sites, users, themes, plugins). Never remove the Super Admin role on a Multisite network.

The Capability System

A capability is a single permission (e.g., edit_posts, delete_pages, moderate_comments, upload_files, switch_themes). A role is a named collection of capabilities.

WordPress uses map_meta_cap internally to translate high‑level capabilities (like edit_others_posts) into specific, user‑‑ or post‑‑scoped actions. This means you usually don’t need to assign raw capabilities directly; instead, assign a role that already has the right bundle.

Key functions

Creating Custom Roles

Option A: Use a plugin (recommended for non‑devs)

Plugins such as User Role Editor or Members provide a dashboard UI to create new roles, add/remove capabilities, and assign roles to users — no code required.

Using User Role Editor

1. Install & activate the plugin from the WordPress.org repository.
2. Go to Users → User Role Editor.
3. Click Add Role, enter a Role Name (machine‑friendly, e.g., contributor_plus) and a Role Label (what users see, e.g., Contributor Plus).
4. Check/uncheck the capabilities you want this role to have. The plugin lists all built‑in capabilities plus any custom ones your theme or other plugins register.
5. Click Add Role. The new role now appears in the user edit screen, where you can assign it to anyone.

Using Members

1. Install & activate Members.
2. Navigate to Members → Roles.
3. Click Add Role, give it a name, and configure the desired capabilities.
4. The plugin also includes a Front End UI role selector you can add to your menu or widget area.

Why use a plugin? Changes are persisted in the database, survive theme changes, and give you a visual map of what each role can do. Ideal for clients who may need to tweak roles later without touching code.

Option B: Code‑first (functions.php)

Developers can register roles programmatically. This is handy when the site is built with a custom theme or when you want the role to be registered on every install.

/**
 * Plugin or theme file: register a "Contributor Plus" role.
 * Give the ability to edit own posts, upload files, but not publish.
 */
add_action( 'init', 'wpb_create_contributor_plus_role', 11 );

function wpb_create_contributor_plus_role() {
    // Do nothing if the role already exists (safer).
    if ( ! role_exists( 'contributor_plus' ) ) {
        add_role(
            'contributor_plus',                                 // role name (DB key)
            'Contributor Plus',                                 // display name
            array(
                'read_post'         => true,
                'edit_posts'        => true,
                'upload_files'      => true,
                'publish_posts'     => false,
                'edit_published_posts' => false,
            )
        );
    }
}

To remove a role later:

add_action( 'init', 'wpb_remove_contributor_plus_role' );

function wpb_remove_contributor_plus_role() {
    remove_role( 'contributor_plus' );
}

Safety tip — Always check role_exists() before calling add_role(), because a second call with the same name overwrites the existing capabilities without merging, which can silently strip permissions.

Modifying Existing Built‑in Roles

Using a plugin (safest for most users)

• User Role Editor: select a built‑in role (Administrator, Editor, etc.), check/uncheck capabilities, and click Update Role.
• Members: similar UI, plus the ability to duplicate a role, give it a new name, and assign unique capabilities.

Directly via code (developers only)

add_action( 'init', 'wpb_editor_remove_unfiltered_html' );

function wpb_editor_remove_unfiltered_html() {
    $role = get_role( 'editor' );
    $role->remove_cap( 'unfiltered_html' );
}

Never remove unfiltered_html from the Administrator role unless you have a very good reason — it’s needed for core customization tasks. Removing it from Editor or Author is usually safe if you don’t use the “Allow unfiltered HTML” feature.

Capability Audit Checklist

Before changing any role, ask these questions:

1. What does this user actually need to accomplish? Write down the specific tasks.
2. Is there a built‑in role that already covers those tasks? If yes, assign that role instead of creating a custom one.
3. Will granting this capability break anything? Consider: could the user publish spam? delete critical content? change site settings?
4. Is the capability over‑privileged for the role? For example, giving edit_themes to an Editor is rarely needed.
5. Should unfiltered_html be involved? Only grant if the user truly needs to insert raw HTML/PHP (usually Admins only).
6. Have you tested as that user? Log in as the role (or use the “Switch Role” feature in Members) and perform the expected actions.
7. Is the change documented? Keep a simple note (or a readme in your repo) of why the role was modified, for future reference.

Common Use‑Case Patterns

Tools & Plugins Comparison

Rule of thumb — If the person managing the site may need to make future role changes without code access, use a plugin. If the role is part of a custom build or multisite network setup, code is usually cleaner and more maintainable.

WP-CLI Recipes (for the command‑line friendly)

Example: create a role and assign a capability in one pipeline:

wp role create client_reviewer "Client Reviewer"
wp cap add client_reviewer edit_posts
wp user add-role 12 client_reviewer   # assign to user ID 12

Further Reading

• WordPress Codex: Roles and Capabilities – the definitive reference.
• WP-CLI role/commands handbook – command‑line role management.
• User Role Editor plugin page – UI‑based role management.
• Members plugin page – advanced role control with front‑end UI.