Skip to main content

​
Overview

Bring Onyx’s AI capabilities directly to your website with an embeddable chat widget. Built with Lit 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: 
<!-- 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.
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.

​
Display Modes

​
Launcher Mode (Default)

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
<onyx-chat-widget mode="launcher"></onyx-chat-widget>

​
Inline Mode

The widget embeds directly in your page layout. Perfect for dedicated support pages or knowledge bases. 
<div style="width: 400px; height: 600px;">
  <onyx-chat-widget mode="inline"></onyx-chat-widget>
</div>
The widget will fill its container’s dimensions in inline mode. Set the container size to control the widget size.

​
Configuration Options

​
Required Attributes

AttributeTypeDescription
backend-urlstringYour Onyx backend API URL
api-keystringAPI key for authentication

​
Optional Attributes

AttributeTypeDefaultDescription
agent-idnumberundefinedSpecific agent/persona to use
agent-namestring"Assistant"Display name in header
logostringOnyx logoURL to custom logo image
primary-colorstring#1c1c1cPrimary brand color (buttons, accents)
background-colorstring#e9e9e9Widget background color
text-colorstring#000000bfText color (75% opacity black)
modestring"launcher"Display mode: "launcher" or "inline"

​
Configuration Examples

Basic Setup: 
<onyx-chat-widget
  backend-url="https://cloud.onyx.app/api"
  api-key="on_abc123">
</onyx-chat-widget>
Full Customization: 
<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 VariableDefaultDescription
--onyx-primary#1c1c1cButtons, accents
--onyx-primary-hover#000000Hover state
--onyx-background#e9e9e9Widget background
--onyx-text#000000bfText (75% opacity)
--onyx-text-light#ffffffWhite text on dark
--onyx-border#00000033Borders (20% opacity)
Override via attributes: 
<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.
Need help with setup? Contact your Onyx administrator for API key configuration or deployment assistance.