useCapxulOrgMembers

Query hook for an organization's member list — the people who hold authority inside the org, scoped by org id.

Reads an organization's members — the people who hold authority inside the org: a role and the caps that come with it. Membership is about authority, not money flow: being paid by an org does not make someone a member; inviting them with a role via useCapxulInviteMember does.

Import

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

Usage

"use client";

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

function MemberList({ orgId }: { orgId: OrgId }) {
  const members = useCapxulOrgMembers(orgId);

  if (members.isLoading) return <p>Loading members…</p>;
  if (members.error) return <p>{members.error.message}</p>;
  if (members.data.length === 0) return <p>No members yet.</p>;

  return (
    <ul>
      {members.data.map((member) => (
        <li key={`${member.orgId}:${member.email}`}>
          <strong>{member.email}</strong> · {member.role} · {member.status}
        </li>
      ))}
    </ul>
  );
}

Parameters

orgId

OrgId | undefined

The organization whose members to read. The query stays disabled while orgId is undefined, so you can pass the result of another query directly — no manual gating needed.

options

UseCapxulOrgMembersOptions | undefined

Prop

Type

Return type

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

data is a list of MemberView records:

Field	Type	Description
`orgId`	`OrgId`	The org this membership belongs to.
`email`	`Email`	The member's email — the universal entry point for inviting.
`name`	`string \| null`	Display name, when known.
`personalSafeAddress`	`Address \| null`	The member-identity key. `null` while the member is still `pending`.
`role`	`string`	The member's role label.
`roleKey`	`RoleKey \| null`	The enforced key the role label maps to. `null` until the grant lands.
`status`	`MemberStatus`	`"pending" \| "pending_safe" \| "pending_grant" \| "active" \| "revoked" \| "expired"`.
`grantTxHash`	`string \| null`	Set once the member's role grant has been recorded.
`revokeTxHash`	`string \| null`	Set once the member's removal has been recorded.

A member starts pending when invited — including people who are not Capxul users yet — moves through provisioning (pending_safe, pending_grant), and becomes active once their role is granted. revoked means they were removed; expired means a pending invitation timed out.

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, "members"] — org-scoped. Invalidated on success by useCapxulInviteMember, useCapxulAssignRole, and useCapxulRemoveMember for the same org.

Client method

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

useCapxulOrgMembers

On this page