> ## Documentation Index
> Fetch the complete documentation index at: https://dev-docs.persona.hasanraiyan.me/llms.txt
> Use this file to discover all available pages before exploring further.
# React SDK Quickstart
> Install @personaai/react, wrap your app in PersonaProvider, and build a working chat interface with streaming, threads, and file management in under 100 lines.
`@personaai/react` is the official React SDK for [Persona](https://persona.hasanraiyan.me) — a
set of hooks and a context provider that let you build a full-featured chat UI against any
Persona backend (Express, NestJS, or raw runtime) without writing fetch calls, SSE parsers, or
state management by hand.
**v0.3.2, current release.** Requires React 18+.
## Install
```bash theme={null}
npm install @personaai/react
```
```bash theme={null}
pnpm add @personaai/react
```
Peer dependencies: `react >= 18`. No other packages are required.
## Prerequisites
You need a running Persona backend — either:
* [`@personaai/nextjs`](/guides/nextjs/quickstart) mounted in your Next.js app
* [`@personaai/express`](/guides/express/quickstart) mounted in your Express app
* [`@personaai/nestjs`](/guides/nestjs/quickstart) configured in your NestJS module
* A [raw runtime](/guides/runtime/quickstart) on any other host
**On Next.js, install [`@personaai/nextjs`](/guides/nextjs/quickstart) instead of this package.**
It re-exports everything documented here behind a `'use client'` boundary — same hooks, same
provider, one install for both halves of the app.
The React SDK is a **client-side** package. It calls your backend's HTTP routes (`/chat`,
`/threads`, `/files`, `/memory`, `/health`, `/agents`) — it never talks directly to
persona.hasanraiyan.me or holds any credential.
## Set up the Provider
Wrap your app (or the subtree that needs chat) in ``. It takes three things:
* **`baseUrl`** — where your Persona backend is mounted (e.g. `http://localhost:3000/api/persona`)
* **`getAuthToken`** — an async getter for the user's Bearer token (Clerk, JWT, session, whatever your app uses). Omit if your backend doesn't require auth.
* **`defaultAgentId`** — optional; lets you skip passing `agentId` to every hook call.
```tsx theme={null}
// app/providers.tsx (Next.js App Router example)
'use client';
import { PersonaProvider } from '@personaai/react';
export function Providers({ children }: { children: React.ReactNode }) {
return (
{
// Your auth — Clerk, NextAuth, a JWT, a cookie, whatever.
const token = await getToken();
return token;
}}
defaultAgentId="my-agent-id"
>
{children}
);
}
```
```tsx theme={null}
// app/layout.tsx
import { Providers } from './providers';
export default function RootLayout({ children }) {
return (
{children}
);
}
```
The Provider is a standard React Context — it doesn't render anything, just makes `fetchWithAuth`
available to every hook downstream. Every hook must be called inside this provider.
## Minimal chat example
Here's a complete, working chat UI in one file — streaming messages, input box, and error
handling:
```tsx theme={null}
'use client';
import { useChat, useAgents } from '@personaai/react';
export function SimpleChat() {
const { agents } = useAgents();
const agentId = agents[0]?._id; // pick your default agent
const {
messages,
input,
setInput,
handleSubmit,
isStreaming,
error,
stop,
} = useChat({ agentId });
return (
{/* Message list */}
{messages.map((msg) => (
{msg.content}
{msg.isStreaming && (
▊
)}
))}
{/* Error banner */}
{error && (
{error.message}
)}
{/* Input */}
);
}
```
That's a fully working chat — streaming text, stop button, error display, and loading states.
The `useChat` hook handles SSE parsing, message state, abort controllers, and thread management
internally.
## Adding thread history
Wrap your chat in a sidebar that lists past conversations:
```tsx theme={null}
'use client';
import { useChat, useThreads } from '@personaai/react';
export function ChatWithThreads() {
const {
threads,
createThread,
deleteThread,
renameThread,
isLoading: threadsLoading,
} = useThreads();
const {
messages,
input,
setInput,
handleSubmit,
sendMessage,
isStreaming,
error,
stop,
reload,
interrupt,
resumeInterrupt,
} = useChat({ threadId: undefined }); // threadId managed below
// Thread selection with lazy creation
const [activeThreadId, setActiveThreadId] = useState();
const handleNewChat = () => {
setActiveThreadId(undefined);
};
const handleSelectThread = (id: string) => {
setActiveThreadId(id);
};
return (
{/* Sidebar */}
{threadsLoading ? (
Loading...
) : (
threads.map((t) => (
))
)}
{/* Main chat area — same as the simple example above */}
{/* ... messages, input, error ... */}
);
}
```
## How sendMessage works
`sendMessage` is the raw send function. It takes:
1. **`content`** (optional) — the message text. If omitted, uses the current `input` value.
2. **`overrideOptions`** (optional) — `{ agentId?, threadId?, resume? }` to override the
hook-level defaults for this specific send.
```tsx theme={null}
// Send with defaults
sendMessage();
// Send specific content
sendMessage('What files do we have?');
// Send to a different agent, in a different thread
sendMessage('Hello', {
agentId: 'other-agent-id',
threadId: 'thread-abc-123',
});
// Resume a paused HITL/clarification interrupt
sendMessage('Approved', {
resume: { decisions: [{ type: 'approve', message: 'Looks good' }] },
});
```
When `threadId` is not set and this is the first message, `useChat` will fail unless your
backend supports implicit thread creation. Use `useThreads().createThread()` first if you need
explicit thread management.
## Handling interrupts (HITL & clarifications)
When the agent pauses for human-in-the-loop approval or a clarification question, the hook
exposes an `interrupt` object. Render it and call `resumeInterrupt` when the user responds:
```tsx theme={null}
if (interrupt) {
if (interrupt.kind === 'hitl') {
// Agent wants approval for one or more tool actions
interrupt.actionRequests.map((req) => (
Agent wants to: {req.name}
{JSON.stringify(req.args, null, 2)}
))
}
if (interrupt.kind === 'clarification') {
// Agent is asking the user a question with options
interrupt.questions.map((q) => (
{q.text}
{q.options.map((opt) => (
))}
))
}
}
```
## Full return value of useChat
```ts theme={null}
const {
messages, // PersonaMessage[] — all messages in the conversation
input, // string — current input value
setInput, // (value: string) => void — update input
handleInputChange, // (e: ChangeEvent) => void — wired to onChange
handleSubmit, // (e?: FormEvent) => void — wired to