Website Widget
Embed Nexus AI chat on any website
Availability depends on your school's enabled tools, provider setup, and account permissions. These settings are managed in the web workspace. A class policy may restrict a feature described here.
Overview#
Bring Nexus'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 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
Source Citations - Optional citation badges linking to source documents
Quick Start#
Add these few lines to your website:
<!-- Load the widget -->
<script type="module" src="https://cdn.onyx.app/widget/1.1/dist/onyx-widget.js"></script>
<!-- Configure and display -->
<onyx-chat-widget
backend-url="https://school.narb.cc/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.
<onyx-chat-widget mode="inline"></onyx-chat-widget>
The widget will fill its container's dimensions in inline mode. Set the container size to control the widget size.
Configuration Options#
Required Attributes#
| Attribute | Type | Description |
|---|---|---|
backend-url | string | Your Nexus 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 | Nexus 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" |
include-citations | boolean | false | Show citation badges linking to source documents |
Citations and private documents: When
include-citationsis enabled, the widget will cite any documents accessible to the configured agent or API key. If the agent has access to private or internal documents, citation links may point to resources that end users cannot view. Scope the agent's document access appropriately, or disable citations for public-facing deployments with sensitive sources.
Configuration Examples#
Basic Setup:
<onyx-chat-widget
backend-url="https://school.narb.cc/api"
api-key="on_abc123">
</onyx-chat-widget>Full Customization:
<onyx-chat-widget
backend-url="https://school.narb.cc/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"
include-citations="true"
> </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:
<onyx-chat-widget
primary-color="#FF6B35"
background-color="#FFFFFF"
text-color="#1A1A1A"
> </onyx-chat-widget>Architecture#
The widget communicates directly with your Nexus 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 Nexus API
User sends message - Request is sent to your Nexus 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 Nexus administrator for API key configuration or deployment assistance.