> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kavachos.com/llms.txt
> Use this file to discover all available pages before exploring further.
# React hooks
> Wire KavachOS into React 18 apps via KavachProvider and hooks from @kavachos/react. Supports Next.js App Router, Pages Router, Vite, and edge runtime backends.
## Overview
`@kavachos/react` provides React hooks and a context provider for building auth UIs on top of KavachOS. It works with Next.js App Router, Next.js Pages Router, Vite, and any React 18+ setup.
The package itself has no Node.js dependencies, it runs entirely in the browser. Your KavachOS API handler can sit behind Next.js Edge Runtime, Cloudflare Workers, Deno Deploy, or any other edge runtime, and the hooks talk to it over standard `fetch`.
All hooks must be rendered inside `KavachProvider`. The provider talks to your KavachOS API route, no direct database access from the browser.
## Installation
```bash theme={"system"}
pnpm add @kavachos/react
```
## Provider setup
Wrap your app with `KavachProvider`. In Next.js App Router, create a client component and import it from your root layout.
```tsx theme={"system"}
// app/providers.tsx
'use client';
import { KavachProvider } from '@kavachos/react';
export function Providers({ children }: { children: React.ReactNode }) {
return (
{children}
);
}
```
```tsx theme={"system"}
// app/layout.tsx
import { Providers } from './providers';
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{children}
);
}
```
Path to your KavachOS API handler. Must match the route you mounted in the adapter.Merged into every fetch call. Use this to add custom headers or credentials mode.
Sessions are stored in `localStorage` under the key `kavach_session`. The hooks automatically restore the session on page reload.
## useSession
Returns the raw session object. Useful when you need the session token or expiry directly.
```tsx theme={"system"}
import { useSession } from '@kavachos/react';
function SessionDebug() {
const { session, isLoading } = useSession();
if (isLoading) return
);
}
```
The current session. Null when unauthenticated or still loading.True during the initial session fetch. Promise`}>Force a re-fetch of the session. Call this after making out-of-band auth changes.
## useUser
Returns the authenticated user and a boolean flag. This is the most common hook for protecting UI.
```tsx theme={"system"}
import { useUser } from '@kavachos/react';
function ProfileCard() {
const { user, isAuthenticated, isLoading } = useUser();
if (isLoading) return ;
if (!isAuthenticated) return ;
return (
{user.name}
{user.email}
);
}
```
The authenticated user object. Null when unauthenticated.True when a valid session with a user is present.True during the initial load. Avoid rendering auth-gated UI until this is false.
## useSignIn
Handles email and password sign-in. Returns a `signIn` function and state fields.
The hook posts to `POST /api/kavach/auth/sign-in` (not `/sign-in/email`). Make sure your adapter is mounted at `/api/kavach`.
```tsx theme={"system"}
import { useSignIn } from '@kavachos/react';
import { useRouter } from 'next/navigation';
function SignInForm() {
const { signIn, isLoading, error } = useSignIn();
const router = useRouter();
async function handleSubmit(e: React.FormEvent) {
e.preventDefault();
const form = new FormData(e.currentTarget);
const result = await signIn({
email: form.get('email') as string,
password: form.get('password') as string,
});
if (result.success) router.push('/dashboard');
}
return (
);
}
```
## useSignUp
Handles new account registration. Posts to `POST /api/kavach/auth/sign-up` (not `/sign-up/email`).
```tsx theme={"system"}
import { useSignUp } from '@kavachos/react';
function SignUpForm() {
const { signUp, isLoading, error } = useSignUp();
async function handleSubmit(e: React.FormEvent) {
e.preventDefault();
const form = new FormData(e.currentTarget);
await signUp({
email: form.get('email') as string,
password: form.get('password') as string,
name: form.get('name') as string,
});
}
return (
);
}
```
## useSignOut
Signs the user out and clears the local session. Optionally redirects after sign-out.
```tsx theme={"system"}
import { useSignOut } from '@kavachos/react';
function NavBar() {
const { signOut } = useSignOut();
return (
);
}
```
## useAgents
Lets your UI create, list, and revoke agents without going through a custom API route.
```tsx theme={"system"}
import { useAgents } from '@kavachos/react';
function Dashboard() {
const { user, isAuthenticated, isLoading } = useUser();
const { agents, create, revoke, isLoading: agentsLoading } = useAgents();
if (!isAuthenticated) return null;
async function handleCreate() {
await create({
name: 'my-bot',
type: 'autonomous',
permissions: [
{ resource: 'reports:*', actions: ['read'] },
],
});
}
return (
{agentsLoading &&
Loading agents...
}
{agents.map((agent) => (
{agent.name}
))}
);
}
```
Current list of agents for the authenticated user. Promise`}>Create a new agent. The list refreshes automatically on success. Promise`}>Revoke an agent by ID. Removes it from the local list on success. Promise`}>Re-fetch the agent list manually.True during the initial agents fetch.
## Next steps
Server-side and Node.js usage with @kavachos/client.
How agents are modelled and what fields they carry.
Mount the KavachOS handler in Next.js, Express, Hono, and others.