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

# React UI Kit

> Production-ready React components for AI chat interfaces. Install @cuadra-ai/uikit and embed a full chat experience in minutes.

## Installation

```bash theme={null}
npm install @cuadra-ai/uikit
```

Requires React 18+. Styles are bundled—no additional CSS imports needed.

***

## Quick Start

```tsx theme={null}
import { CuadraChat } from '@cuadra-ai/uikit';

function App() {
  return (
    <div style={{ height: '100vh' }}>
      <CuadraChat
        connection={{
          baseUrl: "https://api.cuadra.ai",
          sessionToken: "your-session-token"
        }}
        chat={{ modelId: "your-model-id" }}
      />
    </div>
  );
}
```

Get your model ID from [Dashboard](https://dashboard.cuadra.ai) → **Models**.

***

## Props

### Connection

| Prop           | Type   | Description                                |
| -------------- | ------ | ------------------------------------------ |
| `baseUrl`      | string | API URL (`https://api.cuadra.ai`)          |
| `proxyUrl`     | string | Backend proxy URL (alternative to baseUrl) |
| `sessionToken` | string | JWT session token                          |

### Chat

| Prop                | Type                            | Default       | Description                                |
| ------------------- | ------------------------------- | ------------- | ------------------------------------------ |
| `modelId`           | string                          | —             | Model ID (required if `modelMode='fixed'`) |
| `mode`              | `'singleChat'` \| `'multiChat'` | `'multiChat'` | Single or multi-thread                     |
| `modelMode`         | `'fixed'` \| `'selector'`       | `'fixed'`     | Allow model switching                      |
| `systemPrompt`      | string                          | —             | Override system prompt                     |
| `ephemeral`         | boolean                         | false         | Auto-delete chats                          |
| `enableReasoning`   | boolean                         | false         | Show AI thinking                           |
| `enableAttachments` | boolean                         | false         | File uploads                               |

### UI

| Prop               | Type                                | Default    | Description             |
| ------------------ | ----------------------------------- | ---------- | ----------------------- |
| `theme`            | `'light'` \| `'dark'` \| `'system'` | `'system'` | Color scheme            |
| `showThemeToggle`  | boolean                             | true       | Theme toggle button     |
| `welcomeTitle`     | string                              | —          | Welcome screen heading  |
| `suggestions`      | `{prompt: string}[]`                | —          | Pre-made prompts        |
| `inputPlaceholder` | string                              | —          | Input field placeholder |

### Callbacks

| Prop            | Type                     | Description      |
| --------------- | ------------------------ | ---------------- |
| `onChatCreated` | `(id: string) => void`   | New chat created |
| `onError`       | `(error: Error) => void` | Error occurred   |
| `onModelChange` | `(id: string) => void`   | Model changed    |

***

## Examples

### With Suggestions

```tsx theme={null}
<CuadraChat
  connection={{ baseUrl: "https://api.cuadra.ai", sessionToken: token }}
  chat={{ modelId: "model_abc" }}
  ui={{
    welcomeTitle: "How can I help?",
    suggestions: [
      { prompt: "What can you do?" },
      { prompt: "Show me examples" }
    ]
  }}
/>
```

### Model Selector

```tsx theme={null}
<CuadraChat
  connection={{ baseUrl: "https://api.cuadra.ai", sessionToken: token }}
  chat={{ modelMode: "selector" }}
  callbacks={{ onModelChange: (id) => console.log('Model:', id) }}
/>
```

### Proxy Mode (Production)

Route requests through your backend to hide tokens:

```tsx theme={null}
<CuadraChat
  connection={{ proxyUrl: "/api/chat" }}
  chat={{ modelId: "model_abc" }}
/>
```

Your backend handles authentication and forwards to Cuadra AI.

### External Controls

```tsx theme={null}
import { CuadraChat, CuadraChatProvider, useCuadraChat } from '@cuadra-ai/uikit';

function SendButton() {
  const { controls, isReady } = useCuadraChat();
  return (
    <button onClick={() => controls?.sendMessage('Hello!')} disabled={!isReady}>
      Send
    </button>
  );
}

function App() {
  return (
    <CuadraChatProvider>
      <SendButton />
      <CuadraChat connection={{...}} chat={{...}} />
    </CuadraChatProvider>
  );
}
```

***

## Theming

Override CSS variables:

```css theme={null}
:root {
  --cuadra-primary: #6366f1;
  --cuadra-background: #ffffff;
  --cuadra-text: #1f2937;
}

[data-theme="dark"] {
  --cuadra-primary: #818cf8;
  --cuadra-background: #111827;
  --cuadra-text: #f9fafb;
}
```

***

## Widget Mode (No Build)

Embed via script tag for non-React sites:

```html theme={null}
<div id="cuadra-chat" style="height: 100vh;"></div>
<link rel="stylesheet" href="https://unpkg.com/@cuadra-ai/uikit/dist/widget/cuadra-uikit.css">
<script src="https://unpkg.com/@cuadra-ai/uikit/dist/widget/cuadra-uikit.umd.js"></script>
<script>
  CuadraUIKit.init({
    baseUrl: 'https://api.cuadra.ai',
    sessionToken: 'your-token',
    modelId: 'your-model-id'
  });
</script>
```

***

## FAQ

### Do I need a backend?

For production: yes. Never expose session tokens in client-side code. Use `proxyUrl` to route requests through your backend.

### Does it support SSR?

The component is client-side only. Use dynamic imports with `ssr: false` in Next.js:

```tsx theme={null}
const CuadraChat = dynamic(() => import('@cuadra-ai/uikit').then(m => m.CuadraChat), { ssr: false });
```

### Can I customize the message rendering?

Not currently. The UI Kit provides opinionated styling. For full control, use the Chat API directly with your own components.

### How do I handle authentication?

Get session tokens from your auth system (Stytch B2B) and pass to the `sessionToken` prop. Tokens refresh automatically with your auth flow.

***

## Related

<CardGroup cols="2">
  <Card title="Build a Chatbot" icon="robot" href="/guides/tutorial-chatbot">
    Full tutorial with backend
  </Card>

  <Card title="Authentication" icon="lock" href="/api-reference/authentication">
    Token setup
  </Card>
</CardGroup>