useCapxulSwitchActingEntity

Mutation hook that marks a switch between acting as yourself and acting as an organization — a UI seam with no server call.

Switches the acting entity — whether your UI is operating as the personal account or as one of your organizations. In the Capxul SDK there is no global "acting as" state: every org read and mutation names its org explicitly (client.org(orgId)), so the acting entity is state your app owns. This hook is the stable mutation seam to drive that switch through — it gives you isPending for disabling the switcher and a promise for sequencing navigation — and it performs no network call. List the orgs to switch between with useCapxulOrgs.

Import

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

Usage

"use client";

import { useState } from "react";
import type { OrgId } from "@capxul/sdk";
import { useCapxulOrgs, useCapxulSwitchActingEntity } from "@capxul/sdk-react";
import { toOrgId } from "@capxul/types";

function EntitySwitcher({
  onSwitch,
}: {
  onSwitch: (orgId: OrgId | undefined) => void;
}) {
  const orgs = useCapxulOrgs();
  const switchEntity = useCapxulSwitchActingEntity();
  const [value, setValue] = useState("personal");

  const handleChange = async (next: string) => {
    setValue(next);
    const orgId = next === "personal" ? undefined : toOrgId(next);
    await switchEntity.mutateAsync(orgId === undefined ? undefined : { orgId });
    onSwitch(orgId);
  };

  return (
    <select
      value={value}
      disabled={switchEntity.isPending || orgs.isLoading}
      onChange={(event) => void handleChange(event.target.value)}
    >
      <option value="personal">Personal account</option>
      {orgs.data?.map((org) => (
        <option key={org.id} value={org.id}>
          {org.name}
        </option>
      ))}
    </select>
  );
}

Parameters

The hook itself takes no parameters. The mutation takes a SwitchActingEntityInput, or undefined to switch back to acting as yourself:

Prop

Type

Return type

import { type UseCapxulSwitchActingEntityReturn } from "@capxul/sdk-react";
// UseMutationResult<void, Error, SwitchActingEntityInput | undefined>

There is no payload — data is void. Because this mutation never talks to the server, its error type is a plain Error rather than a CapxulError, and in practice it does not fail.

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

This mutation invalidates nothing. Org-scoped queries are keyed by org id (["capxul", "org", orgId, …]), so cached data for the personal account and for each org coexist — nothing needs flushing when the acting entity changes.

Client method

This hook wraps no client method. The core SDK scopes every call explicitly via client.org(orgId), so switching the acting entity is purely a consumer-side state change.