How to Add a Custom User Role in WordPress

WordPress ships with roles such as Subscriber, Contributor, Author and Editor, but you can register your own with add_role(). The snippet below adds an Applicant role, for example for people who sign up through a front-end form and shouldn’t be able to do anything in the admin.

Add it to your child theme’s functions.php or a small plugin.

add_role('applicant', __(
   'Applicant'),
   array(
       'read'            => false, // Allows a user to read
       'create_posts'      => false, // Allows user to create new posts
       'edit_posts'        => false, // Allows user to edit their own posts
       'edit_others_posts' => false, // Allows user to edit others posts too
       'publish_posts' => false, // Allows the user to publish posts
       'manage_categories' => false, // Allows user to manage post categories
       )
);

How it works

• The first argument is the role slug (applicant), the second is the name shown in the admin, made translatable with __(), and the third is an array of capabilities.
• Each key in the array is a capability: true grants it, false denies it. Here every capability is false, including read, so applicants can’t access the WordPress admin.
• Set a value to true for anything the role should be allowed to do, or add other capabilities, such as upload_files.

Things to know

• WordPress saves roles in the database, so the role stays even if you remove the code later. The code only needs to run once; in a plugin, the activation hook is a good place for it.
• add_role() does nothing if the role already exists, so editing the capabilities in this code won’t update an existing role. Remove it first with remove_role( 'applicant' ), or change single capabilities with get_role( 'applicant' )->add_cap().
• If the site is translated, add your text domain to __(), for example __( 'Applicant', 'your-textdomain' ).

Related articles

• adding a plugin admin menu page: menu pages only appear for roles with the capability you set
• letting chosen roles skip ACF required fields: a role-based rule in practice