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

# Mascotbot React SDK Documentation

> Learn how to install and use the Mascotbot SDK with React.

# Mascotbot React SDK

`@mascotbot/react` is the React layer of the Mascotbot avatar SDK.
It gives you a provider, a few hooks, and a thin set of Rive components.
Speech goes in; the avatar speaks in real time.

This page is the map. Each area links to its dedicated guide.

## Install

```ini .npmrc theme={null}
@mascotbot:registry=https://npm.mascot.bot/
//npm.mascot.bot/:_authToken=mascot_xxx
```

<CodeGroup>
  ```bash pnpm theme={null}
  pnpm add @mascotbot/react
  pnpm add @rive-app/react-webgl2 @rive-app/webgl2
  ```

  ```bash npm theme={null}
  npm i @mascotbot/react
  npm i @rive-app/react-webgl2 @rive-app/webgl2
  ```

  ```bash yarn theme={null}
  yarn add @mascotbot/react
  yarn add @rive-app/react-webgl2 @rive-app/webgl2
  ```
</CodeGroup>

`@rive-app/react-webgl2` + `@rive-app/webgl2` are optional peer dependencies of
the `/rive` subpath — install them only when you render an avatar. Full
registry and key setup is in [Installation](/installation).

## The two subpaths

| Import                  | Provides                                                                                                              |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `@mascotbot/react`      | `MascotProvider`, `useMascot`, `useProcessAudio` — the audio pipeline + the top-level provider.                       |
| `@mascotbot/react/rive` | `Mascot`, `MascotRive`, `useMascotRive`, `useMascotInputs`, `useMascotPlayback`, `useLipsyncStream` — the Rive layer. |

## Composition

One provider, one component. `<MascotProvider>` owns the licensed
inference engine; `<Mascot>` mounts the Rive avatar inside it.

```tsx theme={null}
"use client";
import { MascotProvider } from "@mascotbot/react";
import { Mascot, Fit, Alignment } from "@mascotbot/react/rive";

export default function App() {
  return (
    <MascotProvider apiKey="mascot_pub_…">
      <Mascot
        src="/mascot-fox.riv"
        layout={{ fit: Fit.Contain, alignment: Alignment.Center }}
      />
    </MascotProvider>
  );
}
```

| Component                     | Purpose                                                                                                                                                                                                           |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<MascotProvider apiKey="…">` | Initializes one `LipsyncClient` and exposes it to descendants. Props extend the [client config](/installation#4-configure-the-client).                                                                            |
| `<Mascot src=… \| rive=…>`    | Loads Rive and exposes its inputs via context. Pass a `.riv` URL **or** a pre-loaded Rive instance. Renders the canvas by default; children opt out and take control (you can still use `<MascotRive />` inside). |
| `<MascotRive>`                | The canvas component. Use it inside `<Mascot>` children when you need a custom loading slot or layout wrapper; otherwise `<Mascot>` mounts it for you.                                                            |

<Tip>
  `<Mascot>` accepts a pre-loaded `rive` instance you constructed
  yourself. The SDK only writes the mouth, `is_speaking`, and `stress` —
  everything else stays yours. See [Rive co-existence](/concepts/rive-coexistence).
</Tip>

## Where to go next

<Columns cols={2}>
  <Card title="Hooks reference" icon="react" href="/libraries/react-hooks">
    `useMascot`, `useProcessAudio`, `useMascotRive`, `useMascotInputs`,
    `useMascotPlayback`, `useLipsyncStream`, and more.
  </Card>

  <Card title="Offline lip sync" icon="box-archive" href="/libraries/offline-lipsync">
    Generate a timeline once, persist it, replay with zero reprocessing.
  </Card>

  <Card title="Streaming & microphone" icon="microphone" href="/libraries/streaming-and-mic">
    `useLipsyncStream` for mic, tapped `MediaStream`, and manual audio.
  </Card>

  <Card title="Natural lip sync" icon="masks-theater" href="/libraries/natural-lip-sync">
    Smoother, less robotic mouth movement.
  </Card>

  <Card title="Realtime providers" icon="bolt" href="/realtime/overview">
    OpenAI Realtime, Gemini Live, ElevenLabs.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/libraries/react-troubleshooting">
    Common integration issues and fixes.
  </Card>
</Columns>

## WebGL2 rendering

The Rive avatar renders through `@rive-app/*-webgl2`: hardware-accelerated,
smoother animation, advanced effects, efficient memory, and good scaling with
multiple mascots. WebGL2 is required for the renderer (the audio pipeline does
not need it).