useCapxulSignIn

Mutation hook for starting email OTP sign-in — sends the one-time code to the user's email.

Starts email OTP sign-in: sends a one-time code to the given email address. Pair it with useCapxulVerifyOtp to complete the login.

Import

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

Usage

"use client";

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

function SignInForm({ onOtpSent }: { onOtpSent: (email: string) => void }) {
  const signIn = useCapxulSignIn();
  const [email, setEmail] = useState("");

  return (
    <form
      onSubmit={async (event) => {
        event.preventDefault();
        await signIn.mutateAsync({ email });
        onOtpSent(email);
      }}
    >
      <input
        type="email"
        autoComplete="email"
        required
        value={email}
        onChange={(event) => setEmail(event.target.value)}
      />
      <button type="submit" disabled={signIn.isPending}>
        {signIn.isPending ? "Sending…" : "Send code"}
      </button>
      {signIn.error ? <p>{signIn.error.message}</p> : null}
    </form>
  );
}

Sending the code does not sign the user in — useCapxulSession stays null until the code is verified. If the email has never signed in before, the user identity is created during verification, not here.

Parameters

The hook itself takes no parameters. The mutation takes a SignInInput:

Return type

import { type UseCapxulSignInReturn } from "@capxul/sdk-react";
// UseMutationResult<SignInSuccess, CapxulError, SignInInput>

On success, data is a SignInSuccess:

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

Sending an OTP does not change any signed-in state, so this mutation invalidates nothing. The auth boundary (session, profile, account queries) is invalidated by useCapxulVerifyOtp and useCapxulSignOut.

Errors

Failures surface as a CapxulError on error / thrown from mutateAsync — for example when the email is rejected or OTP sending is unavailable for the key's environment.

Client method

This hook wraps client.auth.signIn(input) on the core SDK.