useCapxulAssignRole
Mutation hook for assigning a role to an organization member, keyed by the member's identity address.
Assigns a role to an existing member of an organization — changes their
authority: what they can spend and manage inside the org. The member is
identified by their personalSafeAddress, taken from the member's row in
useCapxulOrgMembers; the
role label must be one of the org's roles (see
useCapxulOrgRoles).
Import
import { useCapxulAssignRole } from "@capxul/sdk-react";Usage
"use client";
import type { MemberView, OrgId } from "@capxul/sdk";
import { useCapxulAssignRole, useCapxulOrgRoles } from "@capxul/sdk-react";
function RolePicker({ orgId, member }: { orgId: OrgId; member: MemberView }) {
const roles = useCapxulOrgRoles(orgId);
const assignRole = useCapxulAssignRole(orgId);
if (member.personalSafeAddress === null) return null;
const memberSafeAddress = member.personalSafeAddress;
return (
<select
value={member.role}
disabled={assignRole.isPending || roles.isLoading}
onChange={(event) =>
assignRole.mutate({ memberSafeAddress, role: event.target.value })
}
>
{roles.data?.map((role) => (
<option key={role.roleKey} value={role.label}>
{role.label}
</option>
))}
</select>
);
}Parameters
orgId
OrgId | undefined
The organization the member belongs to. 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 AssignRoleInput:
| Field | Type | Description |
|---|---|---|
memberSafeAddress | Address | The member's identity key — take it from the member's personalSafeAddress on the MemberView row. |
role | string | The role label to grant — one of the org's roles. The label maps deterministically to the enforced roleKey. |
Return type
import { type UseCapxulAssignRoleReturn } from "@capxul/sdk-react";
// UseMutationResult<MemberView, CapxulError, AssignRoleInput>On success, data is the updated MemberView — see
useCapxulOrgMembers for
the field list.
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 member's new role. The role definitions themselves are
unchanged, so the roles list is not invalidated.
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 grant is rejected.
Client method
This hook wraps client.org(orgId).assignRole(input) — the
entity-scoped org bundle on the core SDK.