> ## 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.
# UIKit Widget
> Embed AI chat in any HTML page with a simple script tag
## Quick Start
Add these lines to your HTML:
```html theme={null}
Chat
```
***
## Installation Options
### CDN (unpkg)
```html theme={null}
```
### CDN (jsDelivr)
```html theme={null}
```
### Self-hosted
Download the files and host them yourself:
```bash theme={null}
npm pack @cuadra-ai/uikit
tar -xzf cuadra-ai-uikit-*.tgz
# Files are in package/dist/widget/
```
***
## Initialization
### JavaScript API
```javascript theme={null}
CuadraUIKit.init({
baseUrl: 'https://api.cuadra.ai',
sessionToken: 'your-session-token',
modelId: 'your-model-id',
mode: 'multiChat',
modelMode: 'fixed',
theme: 'system',
showThemeToggle: true,
welcomeTitle: 'Welcome!',
welcomeSubtitle: 'How can I help you today?',
suggestions: [
{ prompt: 'How do I get started?' },
{ prompt: 'What features do you offer?' }
]
});
```
### Data Attributes (Auto-initialization)
Use data attributes for simpler setup:
```html theme={null}
```
The widget auto-initializes when data attributes are present.
***
## Authentication Options
### Direct API (Bearer Token)
```javascript theme={null}
CuadraUIKit.init({
baseUrl: 'https://api.cuadra.ai',
sessionToken: 'your-session-token',
modelId: 'your-model-id'
});
```
### Proxy Mode
When your backend handles authentication:
```javascript theme={null}
CuadraUIKit.init({
proxyUrl: '/api/chat',
modelId: 'your-model-id'
});
```
***
## Configuration Options
| Option | Type | Default | Description |
| ------------------- | ------- | --------------- | ---------------------------------- |
| `baseUrl` | string | - | Cuadra API URL |
| `proxyUrl` | string | - | Proxy URL for backend auth |
| `sessionToken` | string | - | Bearer token |
| `modelId` | string | - | Model ID |
| `mode` | string | `'multiChat'` | `'singleChat'` or `'multiChat'` |
| `modelMode` | string | `'fixed'` | `'fixed'` or `'selector'` |
| `theme` | string | `'system'` | `'light'`, `'dark'`, or `'system'` |
| `showThemeToggle` | boolean | `true` | Show theme toggle button |
| `language` | string | - | Locale code (e.g., `'en'`, `'es'`) |
| `welcomeTitle` | string | - | Welcome screen title |
| `welcomeSubtitle` | string | - | Welcome screen subtitle |
| `suggestions` | array | - | Array of `{ prompt: string }` |
| `containerId` | string | `'cuadra-chat'` | Target container ID |
| `enableReasoning` | boolean | `false` | Show AI thinking process |
| `enableAttachments` | boolean | `false` | Enable file uploads |
***
## Dynamic Token Updates
Update the session token without re-initializing:
```javascript theme={null}
// Initial setup
CuadraUIKit.init({
baseUrl: 'https://api.cuadra.ai',
sessionToken: initialToken,
modelId: 'your-model-id'
});
// Later, when token refreshes
CuadraUIKit.updateToken(newToken);
```
***
## Full Example
### Basic Implementation
```html theme={null}
Customer Support Chat
```
### Embedded in Existing Page
```html theme={null}
```
### With Proxy Backend
```html theme={null}
```
***
## Styling & Customization
### Container Sizing
The widget fills its container. Control size via the container:
```html theme={null}
```
### Custom Styling
Override CSS variables:
```html theme={null}
```
***
## WordPress Integration
Add to your theme's `footer.php` or use a custom HTML block:
```html theme={null}
```
***
## Troubleshooting
### Widget Not Appearing
1. Check the container exists: `document.getElementById('cuadra-chat')`
2. Ensure CSS is loaded before the script
3. Check browser console for errors
4. Verify container has explicit height
### Authentication Errors
1. Check session token is valid
2. Verify API key has correct permissions
3. Use browser Network tab to inspect requests
### Styling Issues
1. Ensure CSS file is loaded
2. Check for CSS conflicts with your site
3. Use browser DevTools to inspect elements
***
## Next Steps
Use native React components for more control
Build custom chat implementations