useCapxulSubAccountRename

Renames a sub-account — the envelope keeps its id, balance, and history; only the display name changes. Pair it with useCapxulSubAccountsList to show the result.

Import

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

Usage

"use client";

import { useCapxulSubAccountRename } from "@capxul/sdk-react";
import type { SubAccount } from "@capxul/sdk";

function RenameButton({ subAccount }: { subAccount: SubAccount }) {
  const rename = useCapxulSubAccountRename();

  return (
    <button
      type="button"
      disabled={rename.isPending}
      onClick={() =>
        rename.mutate({
          accountId: subAccount.accountId,
          subAccountId: subAccount.id,
          name: "Emergency fund",
        })
      }
    >
      {rename.isPending ? "Renaming…" : "Rename to Emergency fund"}
    </button>
  );
}

Parameters

The hook itself takes no parameters. The mutation input is an object with three fields:

Field	Type	Description
`accountId`	`AccountId`	The parent Account. Carried only so the hook can invalidate the right sub-account list — the rename itself is addressed by `subAccountId`.
`subAccountId`	`SubAccountId`	The sub-account to rename.
`name`	`string`	The new display name. Must be non-empty, at most 64 characters.

Return type

import { type UseCapxulSubAccountRenameReturn } from "@capxul/sdk-react";
// UseMutationResult<SubAccount, CapxulError, { accountId: AccountId; subAccountId: SubAccountId; name: string }>

On success, data is the updated SubAccount with the new name.

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

Field	Description
`mutate`	Fire the mutation (fire-and-forget; pair with `onSuccess`/`onError` callbacks).
`mutateAsync`	Fire the mutation and get a `Promise` of the result. Rejects with a `CapxulError` on failure.
`data`	The mutation result (typed per hook, shown above). `undefined` until the first success.
`error`	A `CapxulError` when the last attempt failed, otherwise `null`.
`isPending`	`true` while the mutation is in flight. Use it to disable submit buttons.
`reset`	Clear the mutation state (`data`, `error`) back to idle.

Mutations do not retry by default. The full field list is in the TanStack Query useMutation reference; see also the TanStack Query integration guide.

Cache behavior

On success this mutation invalidates the Account's sub-account list (["capxul", "subAccounts", accountId]) and the personal balance (["capxul", "accountBalance"]).

Failures surface as a CapxulError on error / thrown from mutateAsync — for example when the name is empty or longer than 64 characters, when the sub-account does not exist, or when the mutation fires while <CapxulProvider> is still bootstrapping.

Client method

This hook wraps client.subAccounts.rename(subAccountId, name) on the core SDK.