React

@cavos/kit ships React bindings under the @cavos/kit/react subpath (same package). Wrap your app once in <CavosProvider> and every descendant can call useCavos() to read wallet state and trigger actions — no prop drilling, no imperative connect calls.

npm install @cavos/kit

import { CavosProvider } from "@cavos/kit/react";

export function Providers({ children }) {
  return (
    <CavosProvider
      config={{
        appId: process.env.NEXT_PUBLIC_CAVOS_APP_ID,
        chains: ["solana", "stellar"],
        defaultChain: "solana",
        network: "testnet",
        appSalt: "my-app",
        socialRecovery: true,   // optional — see Recovery
      }}
      modal={{
        appName: "My App",
        theme: "light",
      }}
    >
      {children}
    </CavosProvider>
  );
}

The provider manages one or more chains. Behind the scenes it resolves the identity, derives addresses for all configured chains, and keeps the wallet handles ready for sponsored transactions. Deployment happens lazily on first execute per chain — see Concepts.

Props

In development the provider checks the config when it mounts and reports problems in the console — a missing appSalt, a paymaster key on a chain that ignores it, and in particular an appSalt that changed since this browser last connected, which silently moves every existing user to a new, empty wallet. Run the same checks yourself with validateCavosConfig(config).

useCavos()

The primary hook. Returns the full wallet surface:

import { useCavos } from "@cavos/kit/react";

function Wallet() {
  const { address, isAuthenticated, walletStatus, openModal, logout } = useCavos();
  if (!isAuthenticated) return <button onClick={openModal}>Sign in</button>;
  return <div>{address} · ready={walletStatus.isReady}</div>;
}

State

WalletStatus: { isDeploying, isReady, isUndeployed, needsDeviceApproval, awaitingApproval, pendingRequestId, hasPasskey, isNewAccount, isSocialRecovering, socialRecoveryReadyAt, recovery }.

• isUndeployed: True when the account has not been deployed on-chain yet. First execute will deploy + run atomically.
• isReady: True when deployed and this device is authorized.
• needsDeviceApproval: True when deployed but this device is not authorized.

walletStatus.recovery is the one flag most apps actually read: { protected: boolean; methods: ("passkey" | "social")[] } — can this user get back in from a device they do not have yet? The other flags describe work in flight; this describes the standing guarantee.

const { walletStatus } = useCavos();
if (walletStatus.isReady && !walletStatus.recovery.protected) {
  // Nudge: "Add a passkey so you can sign in on a new device."
}

Chain switching

Switch the selected chain without re-authenticating or remounting:

const { chain, setChain, configuredChains, session } = useCavos();

// Switch to Stellar
await setChain("stellar");

// Now `chain` is "stellar", `wallet` is the Stellar wallet
// The walletStatus updates to reflect the Stellar account's state

setChain does not re-deploy or re-authenticate — it just changes which wallet is active. The session keeps all chains connected.

Login

Transactions

Device & recovery

When hardware-isolated social recovery is enabled in the selected environment, the dashboard's single provider overrides modal.providers. Email is forced to magic-link mode; OTP is not used for this recovery flow. The provider automatically enrolls a ready wallet after fresh authentication and restores an unregistered device through the attested enclave.

These wrappers present a shared product flow across the current adapters. Their cryptographic implementation and some availability constraints remain chain-specific. See Passkeys and Recovery for the capability details.

Modal & session

useCavosAuth()

A deliberately thin subset for components that only need to open the modal and read basic auth state — no wallet, no transactions:

{
  openModal, closeModal,
  isAuthenticated, address, user, walletStatus, logout,
}

<CavosAuthModal>

A fully customizable, themeable login modal. The provider mounts it automatically when you pass modal={...}; you can also render it directly (for a live preview, or to control its lifecycle yourself).

import { CavosAuthModal } from "@cavos/kit/react";

<CavosAuthModal
  open={open}
  onClose={() => setOpen(false)}
  appName="My App"
  appLogo="https://myapp.com/logo.png"
  appLogoSize={56}
  providers={["email", "google", "apple"]}
  emailMode="otp"
  primaryColor="#402AFF"
  theme="light"
  radius={16}
  secureStep="optional"
/>

Props

CavosModalConfig

The object you pass as modal={...} to <CavosProvider>. Same fields as CavosAuthModalProps except no open / onClose / inline (the provider manages those), plus onSuccess.

Theming

All visual props (primaryColor, theme, backgroundColor, radius, appLogo, appLogoSize) apply identically whether you set them on <CavosProvider modal={...}> or on a direct <CavosAuthModal ... />.

<CavosProvider
  config={{ chains: ["solana"], defaultChain: "solana", network: "testnet", appSalt: "my-app", appId }}
  modal={{
    appName: "My App",
    appLogo: "/logo.png",
    appLogoSize: 48,
    primaryColor: "#7C3AED",
    theme: "dark",
    backgroundColor: "#0A0A0F",
    radius: 20,
  }}
>
  <App />
</CavosProvider>

Mobile: automatic bottom sheet

On viewports max-width: 640px the modal becomes a bottom sheet — it slides up from the bottom with rounded top corners and a grab handle, overlaying the page with a blurred backdrop. This is fully automatic; there is no prop to toggle. On desktop the modal renders centered. The inline mode disables the overlay/sheet entirely (the card is embedded in your layout).

Device approval & revocation pages

Every integrating app needs two routes: one where a user approves a new device, and one where they revoke a device they don't recognise (the links in the device-added email). Both ship ready to mount:

import { ApproveDevicePage } from "@cavos/kit/react";

const configs = [
  { chains: ["starknet"], defaultChain: "starknet", network: "testnet", appSalt: "my-app", appId, paymasterApiKey },
  { chains: ["solana"], defaultChain: "solana", network: "testnet", appSalt: "my-app", appId },
];

export default function Page() {
  return <ApproveDevicePage configs={configs} />;
}

Pass every chain your app supports — the request carries its own network and the page selects the matching config (configForNetwork / chainForNetwork do this, and are exported if you mount the provider yourself). Mounting the wrong chain's provider fails in a way that reads like the device is gone.

RevokeDevicePage is the same flow with the opposite verb. Pass a function as children to keep your own markup — see Multi-device.

Multi-chain in React

The provider handles multiple chains natively. Configure them all up front:

<CavosProvider
  config={{
    chains: ["solana", "stellar", "starknet"],
    defaultChain: "solana",
    network: "testnet",
    appSalt: "my-app",
    appId,
    paymasterApiKey, // for Starknet
  }}
  modal={{ appName: "My App" }}
>
  <App />
</CavosProvider>

Then switch chains without remounting:

function ChainSwitcher() {
  const { chain, setChain, configuredChains, walletStatus } = useCavos();

  return (
    <select value={chain} onChange={(e) => setChain(e.target.value as Chain)}>
      {configuredChains.map((c) => (
        <option key={c} value={c}>{c}</option>
      ))}
    </select>
  );
}

setChain updates the active chain, and walletStatus reflects the new chain's status. No re-authentication, no remount, no lost state.