@rag-widget/chat-widget

Embeddable React chat widget for RAG-powered knowledge bases.

Installation

NPM/Yarn (React Applications)

npm install @rag-widget/chat-widget
# or
yarn add @rag-widget/chat-widget

CDN (Any Website)

<!-- Include React and ReactDOM first -->
<script src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
<script src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>

<!-- Include the widget -->
<script src="https://your-cdn.com/rag-chat-widget.umd.js"></script>

Quick Start

React Application

import { ChatWidget } from '@rag-widget/chat-widget';

function App() {
  return (
    <ChatWidget
      apiKey="rw_live_your_api_key"
      widgetId="your-widget-id"
    />
  );
}

Script Tag (Non-React)

<div id="chat-widget-root"></div>
<script>
  RAGChatWidget.render({
    apiKey: 'rw_live_your_api_key',
    widgetId: 'your-widget-id',
    container: document.getElementById('chat-widget-root')
  });
</script>

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:

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 (
    <div>
      {messages.map(msg => (
        <div key={msg.id} className={msg.role}>
          {msg.content}
        </div>
      ))}
      <input
        onKeyDown={e => {
          if (e.key === 'Enter') {
            sendMessage(e.currentTarget.value);
            e.currentTarget.value = '';
          }
        }}
      />
    </div>
  );
}

Using the Provider

For sharing state across components:

import { ChatWidgetProvider, useChatWidgetContext } from '@rag-widget/chat-widget';

function App() {
  return (
    <ChatWidgetProvider
      apiKey="rw_live_your_api_key"
      widgetId="your-widget-id"
    >
      <ChatMessages />
      <ChatInput />
    </ChatWidgetProvider>
  );
}

function ChatMessages() {
  const { messages, isLoading } = useChatWidgetContext();
  // ...
}

function ChatInput() {
  const { sendMessage } = useChatWidgetContext();
  // ...
}

Styling

The widget comes with default styles. To customize:

CSS Variables

.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;
}

Custom Styles

Import the CSS separately and override:

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
• Domain whitelisting is enforced server-side
• Rate limiting is applied per API key
• Sessions expire after 1 hour of inactivity

Browser Support

• Chrome 60+
• Firefox 55+
• Safari 12+
• Edge 79+

License

MIT