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.isPending) 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. 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

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. This read can also return historical provisioning states. L2 PermissionAssignment state is the authority source for Permission-bound work.

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 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