Invite users to an organization

Learn how to invite new users to an organization

Overview

Organization administrators have the ability to invite new users to their organization and manage those invitations. When an administrator invites a new member, an invitation email is sent out. The invitation recipient can be either an existing user of your application or a new user. If the latter is true, the user will be registered once they accept the invitation.

In React and Next.js applications, the useOrganization() hook returns the organization property, which is then used to call organization.inviteMember() passing in the recipient's email address and desired role (either basic_member or admin).

Administrators are also able to revoke organization invitations for users that have not yet joined, which will prevent the user from becoming an organization member. This is done by calling the revoke() method on the invitations in the invitationList returned by the useOrganization() hook.

Usage

An example implementation in Next.js for inviting users and revoking pending invitations:

1
import { useOrganization } from '@clerk/nextjs';
2
import { useState } from 'react';
3

4
function InviteMember() {
5
  const { organization } = useOrganization();
6
  const [emailAddress, setEmailAddress] = useState('');
7
  const [role, setRole] = useState<'basic_member' | 'admin'>('basic_member');
8
  const [disabled, setDisabled] = useState(false);
9

10
  const onSubmit = async e => {
11
    e.preventDefault();
12
    setDisabled(true);
13
    await organization.inviteMember({ emailAddress, role });
14
    setEmailAddress('');
15
    setRole('basic_member');
16
    setDisabled(false);
17
  };
18

19
  return (
20
    <form onSubmit={onSubmit}>
21
      <input
22
        type="text"
23
        placeholder="Email address"
24
        value={emailAddress}
25
        onChange={e => setEmailAddress(e.target.value)}
26
      />
27
      <label>
28
        <input
29
          type="radio"
30
          checked={role === 'admin'}
31
          onChange={() => {
32
            setRole('admin');
33
          }}
34
        />{' '}
35
        Admin
36
      </label>
37
      <label>
38
        <input
39
          type="radio"
40
          checked={role === 'basic_member'}
41
          onChange={() => {
42
            setRole('basic_member');
43
          }}
44
        />{' '}
45
        Member
46
      </label>{' '}
47
      <button type="submit" disabled={disabled}>
48
        Invite
49
      </button>
50
    </form>
51
  );
52
}
53

54
export default function InvitationList() {
55
  const { invitationList } = useOrganization({ invitationList: {} });
56

57
  if (!invitationList) {
58
    return null;
59
  }
60

61
  const revoke = async inv => {
62
    await inv.revoke();
63
  };
64

65
  return (
66
    <div>
67
      <h2>Invite member</h2>
68
      <InviteMember />
69

70
      <h2>Pending invitations</h2>
71
      <ul>
72
        {invitationList.map(i => (
73
          <li key={i.id}>
74
            {i.emailAddress} <button onClick={() => revoke(i)}>Revoke</button>
75
          </li>
76
        ))}
77
      </ul>
78
    </div>
79
  );
80
}