> ## Documentation Index
> Fetch the complete documentation index at: https://danswer-mintlify-deep-research-1773355783.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Website Widget

> Embed Onyx AI chat on any website

## Overview

Bring Onyx's AI capabilities directly to your website with an embeddable chat widget. Built with [Lit](https://lit.dev/)
web components for maximum compatibility and minimal bundle size.

The widget integrates seamlessly with any website,
providing your visitors instant access to AI-powered conversations without leaving your page.

## Features

* **Lightweight** - \~100-150kb gzipped bundle
* **Fully Customizable** - Colors, branding, and styling to match your site
* **Responsive** - Desktop popup, mobile fullscreen
* **Shadow DOM Isolation** - No style conflicts with your existing CSS
* **Real-time Streaming** - Server-sent events (SSE) for fast responses
* **Session Persistence** - Conversations survive page reloads
* **Two Display Modes** - Floating launcher or inline embed

## Quick Start

Add these few lines to your website:

```html theme={null}
<!-- Load the widget -->
<script type="module" src="https://cdn.onyx.app/widget/1.0/dist/onyx-widget.js"></script>

<!-- Configure and display -->
<onyx-chat-widget
  backend-url="https://cloud.onyx.app/api"
  api-key="your_api_key_here"
  mode="launcher"
>
</onyx-chat-widget>
```

That's it! The widget will appear as a floating button in the bottom-right corner of your page.

<Warning>
  **Always use a limited-scope API key for the widget.** The API key is visible in client-side code,
  so it should have restricted permissions and rate limits. Never use admin or full-access keys.
</Warning>

## Display Modes

### Launcher Mode (Default)

<video src="https://mintcdn.com/danswer-mintlify-deep-research-1773355783/6l4K9uqnjiAmHtjO/assets/overview/onyx_anywhere/widget_popup.mov?fit=max&auto=format&n=6l4K9uqnjiAmHtjO&q=85&s=bd81cb1b428e88a67b4793a82a5809ed" alt="Onyx Widget Chat Popup" autoPlay data-path="assets/overview/onyx_anywhere/widget_popup.mov" />

A floating button appears in the bottom-right corner. Clicking it opens a chat popup.

* **Desktop**: 400x600px popup above the button
* **Mobile**: Full-screen overlay for optimal mobile experience

```html theme={null}
<onyx-chat-widget mode="launcher"></onyx-chat-widget>
```

### Inline Mode

<video src="https://mintcdn.com/danswer-mintlify-deep-research-1773355783/6l4K9uqnjiAmHtjO/assets/overview/onyx_anywhere/widget_inline.mov?fit=max&auto=format&n=6l4K9uqnjiAmHtjO&q=85&s=46af4f812f73d5ca02a8f0f19f342ad6" alt="Onyx Widget Inline Mode" autoPlay data-path="assets/overview/onyx_anywhere/widget_inline.mov" />

The widget embeds directly in your page layout. Perfect for dedicated support pages or knowledge bases.

```html theme={null}
<div style="width: 400px; height: 600px;">
  <onyx-chat-widget mode="inline"></onyx-chat-widget>
</div>
```

<Tip>
  The widget will fill its container's dimensions in inline mode. Set the container size to control the widget size.
</Tip>

## Configuration Options

### Required Attributes

| Attribute     | Type   | Description                |
| ------------- | ------ | -------------------------- |
| `backend-url` | string | Your Onyx backend API URL  |
| `api-key`     | string | API key for authentication |

### Optional Attributes

| Attribute          | Type   | Default       | Description                              |
| ------------------ | ------ | ------------- | ---------------------------------------- |
| `agent-id`         | number | `undefined`   | Specific agent/persona to use            |
| `agent-name`       | string | `"Assistant"` | Display name in header                   |
| `logo`             | string | Onyx logo     | URL to custom logo image                 |
| `primary-color`    | string | `#1c1c1c`     | Primary brand color (buttons, accents)   |
| `background-color` | string | `#e9e9e9`     | Widget background color                  |
| `text-color`       | string | `#000000bf`   | Text color (75% opacity black)           |
| `mode`             | string | `"launcher"`  | Display mode: `"launcher"` or `"inline"` |

### Configuration Examples

**Basic Setup:**

```html theme={null}
<onyx-chat-widget
  backend-url="https://cloud.onyx.app/api"
  api-key="on_abc123">
</onyx-chat-widget>
```

**Full Customization:**

```html theme={null}
<onyx-chat-widget
  backend-url="https://cloud.onyx.app/api"
  api-key="on_abc123"
  agent-id="42"
  agent-name="Support Bot"
  logo="https://yoursite.com/logo.png"
  primary-color="#FF6B35"
  background-color="#FFFFFF"
  text-color="#1A1A1A"
  mode="launcher"
>
</onyx-chat-widget>
```

## Customization

### Styling

The widget uses CSS custom properties for theming.
All styles are scoped within Shadow DOM to prevent conflicts with your site's CSS.

**Default Colors:**

| CSS Variable           | Default     | Description           |
| ---------------------- | ----------- | --------------------- |
| `--onyx-primary`       | `#1c1c1c`   | Buttons, accents      |
| `--onyx-primary-hover` | `#000000`   | Hover state           |
| `--onyx-background`    | `#e9e9e9`   | Widget background     |
| `--onyx-text`          | `#000000bf` | Text (75% opacity)    |
| `--onyx-text-light`    | `#ffffff`   | White text on dark    |
| `--onyx-border`        | `#00000033` | Borders (20% opacity) |

**Override via attributes:**

```html theme={null}
<onyx-chat-widget
  primary-color="#FF6B35"
  background-color="#FFFFFF"
  text-color="#1A1A1A"
>
</onyx-chat-widget>
```

## Architecture

The widget communicates directly with your Onyx backend using Server-Sent Events (SSE)
for real-time streaming responses:

**Widget loads** - Lightweight JavaScript bundle initializes the web component

**Session created** - Widget creates a chat session via the Onyx API

**User sends message** - Request is sent to your Onyx backend

**Streaming response** - AI response streams back in real-time via SSE

**Markdown rendered** - Responses are formatted with full markdown support

## Browser Support

* Chrome/Edge 90+ (Chromium)
* Firefox 90+
* Safari 15+
* Mobile Safari (iOS 15+)
* Mobile Chrome (Android)

## Deployment

For detailed deployment instructions, including self-hosted setup and API key security best practices,
see the [Website Widget Deployment Guide](/deployment/configuration/website_widget).

<Info>
  **Need help with setup?** Contact your Onyx administrator for API key configuration or deployment assistance.
</Info>