useCapxulInviteMember
Mutation hook for creating an Organization invitation by email.
Invites a person into an Organization by email. The role label is
invitation metadata. It does not grant an L2 Permission. 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 | Invitation metadata. It does not authorize an L2 write. |
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.
Client-backed mutation hooks are safe to render while CapxulProvider
bootstraps. If one is fired before bootstrap finishes, mutateAsync rejects
with a CapxulError whose code is WRONG_STATE; applications do not need to
hide their route tree behind useCapxul(). Every shipped mutation hook is
client-backed — alpha.23 removed the one client-free hook
(useCapxulSwitchActingEntity, a documented no-op).
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.