useCapxulOrgRoles

Reads the roles a member can be invited into for an Organization — the roles that carry member-management authority. A Budget is granted, never offered as a job title, so it is not in this list. Role labels and stored spend caps do not authorize an L2 payment. Use the Organization Permission hooks for current authority.

Import

import { useCapxulOrgRoles } from "@capxul/sdk-react";

Usage

"use client";

import type { OrgId } from "@capxul/sdk";
import { useCapxulOrgRoles } from "@capxul/sdk-react";

function RoleList({ orgId }: { orgId: OrgId }) {
  const roles = useCapxulOrgRoles(orgId);

  if (roles.isPending) return <p>Loading roles…</p>;
  if (roles.error) return <p>{roles.error.message}</p>;

  return (
    <ul>
      {roles.data.map((role) => {
        const perTx = role.definition.spend?.perTx;
        return (
          <li key={role.roleKey}>
            {role.label}
            {perTx
              ? ` — up to ${perTx.value} ${perTx.currency} per transaction`
              : " — no per-transaction cap"}
          </li>
        );
      })}
    </ul>
  );
}

Parameters

orgId

OrgId | undefined

The organization whose roles to read. The query stays disabled while orgId is undefined. When the screen must wait for Organization setup, derive options.enabled from the matching ready Organization lane in useCapxulIdentity. A disabled query remains isPending until the gate opens.

options

UseCapxulOrgRolesOptions | undefined

Prop

Type

Return type

import { type UseCapxulOrgRolesReturn } from "@capxul/sdk-react";
// UseQueryResult<readonly RoleView[], CapxulError>

data is a list of RoleView records:

Field	Type	Description
`orgId`	`OrgId`	The org the role is defined on.
`label`	`string`	The role's display label (for example `"Owner"`).
`roleKey`	`RoleKey`	The enforced key, derived deterministically from the label.
`definition`	`RoleDefinition`	The full role definition (below).

A RoleDefinition carries:

Field	Type	Description
`label`	`string`	The role's label.
`spend`	`RoleSpendCap \| undefined`	Historical role metadata. It does not authorize an L2 payment.
`canManageMembers`	`boolean \| undefined`	Whether the role can invite and remove members.
`canManageRoles`	`boolean \| undefined`	Whether the role can manage the role set itself.

The hook returns TanStack Query's UseQueryResult. The most-used fields:

Field	Description
`data`	The query data (typed per hook, shown above). `undefined` until the first success.
`error`	A `CapxulError` when the last fetch failed, otherwise `null`.
`status`	`'pending'` \| `'error'` \| `'success'`.
`isLoading`	`true` during the first fetch (no data yet).
`isFetching`	`true` whenever a fetch is in flight, including background refetches.
`refetch`	Manually refetch the query.

Capxul query hooks stay pending until the provider finishes bootstrapping — you do not need to gate them on useCapxul() yourself. The full field list is in the TanStack Query useQuery reference; see also the TanStack Query integration guide.

Query key

["capxul", "org", orgId, "roles"] — org-scoped.

Client method

This hook wraps client.org(orgId).roles() — the entity-scoped org bundle on the core SDK.

useCapxulOrgRoles

On this page