> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paddock.build/llms.txt
> Use this file to discover all available pages before exploring further.

# React

> @paddock/react: the useSession hook and PaddockProvider.

`@paddock/react` binds the [browser client](https://docs.paddock.build/sdks/client.md) to React 18 or 19 with one hook, `useSession`, and one provider, `PaddockProvider`.

## Install

```bash theme={null}
npm install @paddock/react
```

It depends on `@paddock/client` and takes `react` as a peer dependency.

> [!NOTE]
>
> `@paddock/react` is not on npm yet. Until it is published, build it from the `sdk/js` workspace of the paddock repository.

## useSession

```tsx theme={null}
import { useSession } from "@paddock/react";

export function Session({ sessionId, token }: { sessionId: string; token: string }) {
  const { messages, status, turn, error, processedSeq, send, stop } = useSession(sessionId, { token });

  return (
    <section>
      <header>
        {status}
        {turn && <button onClick={() => void stop()}>Stop</button>}
      </header>
      {error && <p role="alert">{error.code}: {error.message}</p>}
      {messages.map((m) =>
        m.kind === "user" ? (
          <p key={m.id}>
            {m.text} {m.seq !== null && m.seq > processedSeq ? "(waiting)" : ""}
          </p>
        ) : m.kind === "assistant" || m.kind === "streaming" ? (
          <p key={m.id}>{m.text}</p>
        ) : null,
      )}
      <button onClick={() => void send("Go on")}>Go on</button>
    </section>
  );
}
```

`useSession(sessionId, options)` returns the session's [`SessionState`](https://docs.paddock.build/sdks/client#sessionstate) with two functions:

| Returned | Meaning |
| - | - |
| The fields of `SessionState` | `messages`, `status`, `turn`, `error`, `processedSeq`, `heldSeq`, `session`, `connection`, `connectionError`, `events`, `harnessStatus` |
| `send(text)` | Sends a message; resolves with its stored event |
| `stop()` | Stops the running turn; resolves with the stored `stop.requested` event |

| Option | Meaning |
| - | - |
| `token` | The session token |
| `baseUrl` | The API's base URL; default the nearest `PaddockProvider`'s, then `https://api.paddock.build/v1` |

* **Shared connections.** Hooks with the same base URL, token, and session ID share one handle: the stream opens with the first mounted hook and closes with the last. The base URL is compared as given, so a hook that omits it and one that names the default URL do not share.
* **Remounts are cheap.** The page keeps every handle and its state, so a component that remounts resumes the stream without reloading the history.
* **Server rendering.** During server rendering the hook returns the empty initial state and makes no request; the browser loads the session after hydration.
* **New token, new connection.** Passing a new token opens a new connection with it. Do that when `connection` is `closed` because the token expired.

## PaddockProvider

`PaddockProvider` supplies the base URL every `useSession` below it uses unless its own options name one:

```tsx theme={null}
import type { ReactNode } from "react";
import { PaddockProvider } from "@paddock/react";

export function Providers({ children }: { children: ReactNode }) {
  return <PaddockProvider baseUrl="https://api.paddock.build/v1">{children}</PaddockProvider>;
}
```

For a complete chat application, see [Chat app with React](https://docs.paddock.build/examples/react-chat.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.