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,       // enclave DEK wrap (multi-chain OK)
        deviceApproval: "enclave",
      }}
      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, hasPasskey, isNewAccount, recovery }.

• isUndeployed: True when the account has not been deployed on-chain yet. First execute will deploy + run atomically.
• isReady: True when this device holds the wallet key.
• needsDeviceApproval: True when the wallet exists but this device holds no key yet.

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, <CavosProvider> enrolls after a fresh login (reseals the MasterDEK if this device already has it) and unwraps on a device that does not. Passkey is opt-in via enrollPasskeyDefault() — secureStep defaults to 'off'.

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"]}
  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).

New devices

There are no device approval or revocation pages to host. A new device restores the MasterDEK with the enclave or a passkey and derives the same account key; nothing is added on-chain. 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.