useCapxulSubAccountsList

Query hook for an Account's sub-accounts — the named envelopes that partition its balance.

Lists an Account's sub-accounts — named envelopes that partition the Account's money (Rent, Payroll, Emergency fund, …). Whatever is not assigned to an envelope is the Account's main balance; it is a remainder, not a row, so it never appears in this list. Create envelopes with useCapxulSubAccountCreate and fund them with useCapxulTransfer.

Import

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

Usage

"use client";

import { useCapxulAccountBalance, useCapxulSubAccountsList } from "@capxul/sdk-react";

function EnvelopeList() {
  const account = useCapxulAccountBalance();
  const subAccounts = useCapxulSubAccountsList(account.data?.id);

  if (subAccounts.isLoading) return <p>Loading envelopes…</p>;
  if (subAccounts.error) return <p>{subAccounts.error.message}</p>;

  return (
    <ul>
      {subAccounts.data.map((subAccount) => (
        <li key={subAccount.id}>
          {subAccount.name}: {subAccount.balance.value} {subAccount.balance.currency}
        </li>
      ))}
    </ul>
  );
}

Parameters

accountId

AccountId | undefined

The Account whose sub-accounts to list. The query stays disabled while accountId is undefined, so you can pass the id from useCapxulAccountBalance directly — no manual gating needed.

options

UseCapxulSubAccountsListOptions | undefined

Prop

Type

Return type

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

data is an array of SubAccount: the sub-account's opaque id, its parent accountId, its display name, its balance (a Money — currency, decimal value, precision), and createdAt. An Account with no envelopes returns an empty array.

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", "subAccounts", accountId] — scoped per Account, and invalidated automatically by the four sub-account mutations for that Account (useCapxulSubAccountCreate, useCapxulSubAccountRename, useCapxulSubAccountDelete, useCapxulTransfer).

Client method

This hook wraps client.subAccounts.list(accountId) on the core SDK.

useCapxulSubAccountsList

On this page