Embeddable chat widget for RAG-powered knowledge bases
npm install @rag-widget/chat-widgetbash
npm install @rag-widget/chat-widget
or
yarn add @rag-widget/chat-widget
`
$3
`html
`
Quick Start
$3
`tsx
import { ChatWidget } from '@rag-widget/chat-widget';
function App() {
return (
widgetId="your-widget-id"
/>
);
}
`
$3
`html
`
Props
| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| apiKey | string | Yes | - | Your RAG Widget API key |
| widgetId | string | Yes | - | The widget ID to connect to |
| apiBaseUrl | string | No | Current origin | API server URL |
| position | 'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left' | No | 'bottom-right' | Widget position |
| primaryColor | string | No | '#007bff' | Primary theme color |
| greeting | string | No | From config | Initial greeting message |
| placeholder | string | No | From config | Input placeholder text |
| showPoweredBy | boolean | No | From config | Show "Powered by" footer |
| onError | (error: Error) => void | No | - | Error callback |
| onMessageSent | (message: string) => void | No | - | Message sent callback |
| onMessageReceived | (message: Message) => void | No | - | Message received callback |
Using the Hook
For custom implementations, use the useChatWidget hook:
`tsx
import { useChatWidget } from '@rag-widget/chat-widget';
function CustomChat() {
const {
messages,
isLoading,
isConnected,
config,
error,
sendMessage,
clearMessages,
retry
} = useChatWidget({
apiKey: 'rw_live_your_api_key',
widgetId: 'your-widget-id',
apiBaseUrl: 'https://your-api.com'
});
return (
{messages.map(msg => (
{msg.content}
))}
onKeyDown={e => {
if (e.key === 'Enter') {
sendMessage(e.currentTarget.value);
e.currentTarget.value = '';
}
}}
/>
);
}
`
Using the Provider
For sharing state across components:
`tsx
import { ChatWidgetProvider, useChatWidgetContext } from '@rag-widget/chat-widget';
function App() {
return (
widgetId="your-widget-id"
>
);
}
function ChatMessages() {
const { messages, isLoading } = useChatWidgetContext();
// ...
}
function ChatInput() {
const { sendMessage } = useChatWidgetContext();
// ...
}
`
Styling
The widget comes with default styles. To customize:
$3
`css
.rag-chat-widget {
--rag-primary-color: #007bff;
--rag-bg-color: #ffffff;
--rag-text-color: #333333;
--rag-border-color: #e0e0e0;
--rag-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
--rag-font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
}
`
$3
Import the CSS separately and override:
`tsx
import '@rag-widget/chat-widget/dist/styles.css';
// Then add your overrides
`
API Endpoints
The widget communicates with these endpoints:
- GET /api/v1/widget/:widgetId/config - Get widget configuration
- POST /api/v1/widget/:widgetId/query - One-shot query
- POST /api/v1/widget/:widgetId/sessions - Create chat session
- POST /api/v1/widget/:widgetId/sessions/:sessionId/messages - Send message (SSE streaming)
Security
- API keys are sent via X-API-Key` header