`useInvitation()` hook

useInvitation() is the headless invitation-acceptance hook behind <AcceptInvite />. It accepts an invitation token, stores the last returned invitation result, exposes a loading state for the active request, and keeps a reset path so the page can clear the last result before trying again.

Usage

The following example shows a basic usage of useInvitation().

export default function InvitationPage() {  const { acceptInvitation, invitationData, loading, error } = useInvitation();  async function accept() {    await acceptInvitation('invite-token');  }  return (    <div>      <button onClick={accept} disabled={loading}>        Accept invitation      </button>      {error ? <p>{error}</p> : null}      {invitationData?.organization ? <p>{invitationData.organization.name}</p> : null}    </div>  );}

Return value

The hook returns the following fields and methods.

›

acceptInvitation: (token: string) => Promise<AcceptInvitationResponse>;

Accepts an invitation token and returns the invitation result.

›

organization?: { id: string; name: string } | undefined | undefined;

Organization that the invitation belongs to when one is returned.

›

id?: string | undefined;

Organization identifier.

›

name?: string | undefined;

Organization name.

›

workspace?: { id: string; name: string } | undefined | undefined;

Workspace that the invitation belongs to when one is returned.

›

id?: string | undefined;

Workspace identifier.

›

name?: string | undefined;

Workspace name.

›

signin_id?: string | undefined | undefined;

Sign-in identifier returned when the accepted invitation is attached to a specific sign-in.

›

already_member?: boolean | undefined | undefined;

Whether the invited user is already a member.

›

message?: string | undefined | undefined;

Human-readable message returned with the invitation result.

›

requires_signin?: boolean | undefined | undefined;

Whether the user must sign in before the invitation can be completed.

›

invited_email?: string | undefined | undefined;

Email address that the invitation expects.

›

error_code?: string | undefined | undefined;

Error code when the invitation could not be accepted cleanly.

›

invitationData: AcceptInvitationResponse | null;

Last invitation result returned by `acceptInvitation()`.

›

organization?: { id: string; name: string } | undefined | undefined;

Accepted organization when one is returned.

›

workspace?: { id: string; name: string } | undefined | undefined;

Accepted workspace when one is returned.

›

signin_id?: string | undefined | undefined;

Returned sign-in identifier when one is present.

›

already_member?: boolean | undefined | undefined;

Whether the invited user was already a member.

›

message?: string | undefined | undefined;

Returned invitation message.

›

requires_signin?: boolean | undefined | undefined;

Whether the invitation still requires sign-in.

›

invited_email?: string | undefined | undefined;

Expected invited email address.

›

error_code?: string | undefined | undefined;

Returned error code when acceptance failed.

›

loading: boolean;

Whether an invitation-acceptance request is currently running.

›

error: string | null;

Current invitation error message.

›

reset: () => void;

Clears the current error and invitation result so the UI can retry from a clean state.

How it works

The hook stores the last invitation result in local state rather than returning a bare request promise only. That is what lets <AcceptInvite /> render the success, already-member, and sign-in-required branches from one result object.

Network failures and logical invitation failures are both surfaced through the same result shape. On network failure, the hook also synthesizes an error_code so the UI still has structured state to render.

The hook does not decide where to navigate next. Higher-level UI uses the returned requires_signin, invited_email, and membership data to decide whether to continue, send the user to sign-in or sign-up, or show a terminal error state.

Calling acceptInvitation() clears the previous error and invitation result before the next request starts.

When to use it

Examples

Accept an invitation token from your own page

export default function AcceptOrgInvite() {  const { acceptInvitation, invitationData, loading } = useInvitation();  async function accept() {    await acceptInvitation('invite-token');  }  return (    <div>      <button onClick={accept} disabled={loading}>        Accept invitation      </button>      {invitationData?.organization ? (        <p>Joined {invitationData.organization.name}</p>      ) : null}    </div>  );}

Reset the invitation state before retrying

export default function RetryInvitation() {  const { acceptInvitation, error, reset } = useInvitation();  async function retry() {    reset();    await acceptInvitation('invite-token');  }  return (    <div>      <button onClick={retry}>Try again</button>      {error ? <p>{error}</p> : null}    </div>  );}

useInvitation() hook