useCapxulProfile

Query hook for the signed-in user's identity profile — null for a fresh identity until onboarding completes.

Reads the signed-in user's identity profile — display name, country, KYC tier. Distinct from useCapxulSession (am I signed in?) and from useCapxulCurrentUser (the aggregated user + accounts + orgs view).

Import

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

Usage

"use client";

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

function ProfileCard() {
  const profile = useCapxulProfile();

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

  if (!profile.data) {
    // Fresh identity — signed in, but onboarding has not completed yet.
    return <a href="/signup">Finish setting up your account</a>;
  }

  return (
    <div>
      <p>{profile.data.displayName ?? profile.data.email}</p>
      <p>Country: {profile.data.country ?? "—"}</p>
    </div>
  );
}

data can be null for a brand-new identity: OTP verification creates the auth user, but the profile record is created during onboarding / account setup, not at verification. Treat null as "route to onboarding", not as an error.

Parameters

None. The query is gated automatically: it stays pending until the provider finishes bootstrapping, with no manual enabled wiring needed.

Return type

import { type UseCapxulProfileReturn } from "@capxul/sdk-react";
// UseQueryResult<Profile | null, CapxulError>

data is a Profile or null (no profile record yet — see above):

Field	Type	Description
`authUserId`	`string`	The auth user id — same id as `Session.authUserId`.
`email`	`string`	The signed-in email.
`displayName`	`string \| null`	Set during onboarding; `null` until then.
`country`	`string \| null`	ISO-3166 country code, set during onboarding.
`kycTier`	`0 \| 1 \| 2 \| 3`	The identity's verification tier.
`createdAt`	`number`	Epoch milliseconds.
`updatedAt`	`number`	Epoch milliseconds.

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", "profile"] — invalidated (background refetch) by useCapxulVerifyOtp and by the onboarding mutations (useCapxulCompletePersonalOnboarding, useCapxulCompleteOrganizationOnboarding), and reset by useCapxulSignOut.

Client method

This hook wraps client.identity.loadCurrent() on the core SDK.