useCapxulInviteMember
Mutation hook for inviting a member into an organization by email, granting them a role.
Invites a person into an organization by email, granting them a role.
Membership is authority: paying someone from the org does not make them a
member — inviting them with a role does. The email does not need to belong to
an existing Capxul user; inviting a new address creates a pending membership
that resolves when they sign in. See
useCapxulOrgMembers for
reading the resulting member list.
Import
import { useCapxulInviteMember } from "@capxul/sdk-react";Usage
"use client";
import { useState } from "react";
import type { OrgId } from "@capxul/sdk";
import { useCapxulInviteMember } from "@capxul/sdk-react";
function InviteForm({ orgId }: { orgId: OrgId }) {
const invite = useCapxulInviteMember(orgId);
const [email, setEmail] = useState("");
return (
<form
onSubmit={async (event) => {
event.preventDefault();
await invite.mutateAsync({ email, role: "Member" });
setEmail("");
}}
>
<input
type="email"
autoComplete="email"
required
value={email}
onChange={(event) => setEmail(event.target.value)}
/>
<button type="submit" disabled={invite.isPending}>
{invite.isPending ? "Sending…" : "Send invite"}
</button>
{invite.error ? <p>{invite.error.message}</p> : null}
</form>
);
}Parameters
orgId
OrgId | undefined
The organization to invite into. Accepts undefined so you can wire it to a
not-yet-resolved value, but firing the mutation before it resolves rejects
with a CapxulError.
The mutation takes an InviteMemberInput:
| Field | Type | Description |
|---|---|---|
email | string | The invitee's email. They do not need to be a Capxul user yet. |
role | string | The role label the invitee is granted on accept — one of the org's roles (see useCapxulOrgRoles). |
Return type
import { type UseCapxulInviteMemberReturn } from "@capxul/sdk-react";
// UseMutationResult<MemberView, CapxulError, InviteMemberInput>On success, data is the new MemberView — see
useCapxulOrgMembers for
the field list. A fresh invite starts with status pending and stays that way
until the invitee signs in and provisioning completes.
The hook returns TanStack Query's UseMutationResult. The most-used fields:
| Field | Description |
|---|---|
mutate | Fire the mutation (fire-and-forget; pair with onSuccess/onError callbacks). |
mutateAsync | Fire the mutation and get a Promise of the result. Rejects with a CapxulError on failure. |
data | The mutation result (typed per hook, shown above). undefined until the first success. |
error | A CapxulError when the last attempt failed, otherwise null. |
isPending | true while the mutation is in flight. Use it to disable submit buttons. |
reset | Clear the mutation state (data, error) back to idle. |
Mutations do not retry by default. The full field list is in the
TanStack Query useMutation reference;
see also the TanStack Query integration guide.
Cache behavior
On success this mutation invalidates the org's member list
(["capxul", "org", orgId, "members"]), so
useCapxulOrgMembers
refetches with the new pending row. Other orgs' caches are untouched.
Errors
Failures surface as a CapxulError on
error / thrown from mutateAsync — for example when the mutation fires
while orgId is still undefined, or when the invite is rejected.
Client method
This hook wraps client.org(orgId).invite(input) — the
entity-scoped org bundle on the core SDK.