add_role() wordpress function and usage This text is not used because the data attribute has a value

add_role() wordpress function and usage

Home / WordPress / WordPress Wiki / add_role() wordpress function and usage

add_role( string $role, string $display_name, bool[] $capabilities = array() )
Add role, if it does not exist.



(string) (Required) Role name.


(string) (Required) Display name for role.


(bool[]) (Optional) List of capabilities keyed by the capability name, e.g. array( ‘edit_posts’ => true, ‘delete_posts’ => false ).

Default value: array()


(WP_Role|null) WP_Role object if role is added, null if already exists.

Sample Usage

Be sure to use this function (and similar role functions) only in an activation hook or within a conditional block. There is no need for this to execute every time the page loads, and it will keep updating the database every time it’s called.

For example, this will store an option to track the version of the custom roles and will only update the database once:

function xx__update_custom_roles() {
    if ( get_option( 'custom_roles_version' ) < 1 ) {
        add_role( 'custom_role', 'Custom Subscriber', array( 'read' => true, 'level_0' => true ) );
        update_option( 'custom_roles_version', 1 );
add_action( 'init', 'xx__update_custom_roles' );

You can also easily create a new user role based on an existing user role.
( equivalent to WP CLI: wp role create <role-key> <role-name> --clone=<role> )

Example: create a role Superintended with the same capabilities as Administrator

add_role( 'superintendent', 'Superintendent', get_role( 'administrator' )->capabilities );

Create a new role when a plugin is activated
See register_activation_hook.

function add_roles_on_plugin_activation() {
       add_role( 'custom_role', 'Custom Subscriber', array( 'read' => true, 'level_0' => true ) );
register_activation_hook( __FILE__, 'add_roles_on_plugin_activation' );

Note: Delete existing role
You can not change the capabilities of an existing role using add_role(). This function will stop executing and return null is the specified role name already exists.

You can change a user role’s capabilities (or display name) by using remove_role(), then add_role().

This is for development only. Once you have nailed down your list of capabilities, there’s no need to keep the remove_role() code.

Create a new “Guest Author” role.

$result = add_role(
    __( 'Guest Author', 'testdomain' ),
        'read'         => true,  // true allows this capability
        'edit_posts'   => true,
        'delete_posts' => false, // Use false to explicitly deny
if ( null !== $result ) {

Note: When to call
Make sure the global $wp_roles is available before attempting to add or modify a role. The best practice is to use a plugin (or theme) activation hook to make changes to roles (since you only want to do it once!).

mu-plugins loads too early, so use an action hook (like 'init') to wrap your add_role() call if you’re doing this in the context of an mu-plugin.


<?php add_role( $role, $display_name, $capabilities ); ?>


0 0 votes
Article Rating
Notify of
Inline Feedbacks
View all comments