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,
        chain: "solana",        // "starknet" | "solana" | "stellar"
        network: "testnet",     // resolves to the chain's devnet/sepolia
        appSalt: "my-app",
      }}
      modal={{
        appName: "My App",
        theme: "light",
      }}
    >
      {children}
    </CavosProvider>
  );
}

The provider manages exactly one chain. Behind the scenes it resolves the identity, deploys the device-signer account gaslessly on first use, and keeps the wallet handle ready for sponsored transactions. See Chains for the chain model.

useCavos()

The primary hook. Returns the full wallet surface:

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

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

State

WalletStatus: { isDeploying, isReady, needsDeviceApproval, awaitingApproval, pendingRequestId, hasPasskey, isNewAccount }. Gate any transaction on walletStatus.isReady.

Login

Transactions

Device & recovery

These wrappers are chain-agnostic — they work the same on Starknet, Solana, and Stellar. See Passkeys and Recovery for the full lifecycle.

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={{ chain: "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).

Multi-chain in React

The provider is single-chain by design. To let a user switch chains, remount the provider with a new key — this resets auth state and connects a fresh wallet for the new chain:

const [chain, setChain] = useState<"solana" | "stellar" | "starknet">("solana");

<CavosProvider key={chain} config={{ chain, network: "testnet", appSalt: "my-app", appId }}>
  <App onChainChange={setChain} />
</CavosProvider>