useCapxulOrgs

Returns one canonical OrganizationAccess per accessible Organization. List inclusion does not prove active membership or authority to read treasury or members. Use scoped methods for those reads.

Import

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

Usage

"use client";

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

function OrgList() {
  const orgs = useCapxulOrgs();

  if (orgs.isLoading) return <p>Loading organizations…</p>;
  if (orgs.error) return <p>Could not load your Organizations ({orgs.error.code}).</p>;

  return (
    <ul>
      {(orgs.data ?? []).map((org) => (
        <li key={org.id}>
          {org.name} <span>@{org.handle}</span>
        </li>
      ))}
    </ul>
  );
}

Parameters

options

UseCapxulOrgsOptions | undefined

Prop

Type

This is a session-scoped authenticated read. Firing it before the session has settled surfaces a spurious NOT_AUTHENTICATED error, so gate it on auth readiness when the surface can render before sign-in completes:

const identity = useCapxulIdentity();
const orgs = useCapxulOrgs({ enabled: identity.phase === "authenticated" });

Return type

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

data contains the SDK's OrganizationAccess records without a React projection. Each record carries id, name, handle, account, setup, member, capabilities, custody, and observedAt. The Organization address is account.address. Account ID and readiness can be null. A founder setup can have member: null. Unknown custody is { status: "unknown" }. The list has no role, treasury snapshot, or profile fields.

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", "orgs"] — invalidated on success by useCapxulCreateOrg.

Client method

This hook wraps client.orgs() on the core SDK.