Embeddable AI chatbot widget with React support for AsterMind RAG
Embeddable AI chatbot widget for AsterMind RAG - a drop-in chat UI that connects to your AsterMind backend with full agentic capabilities.


---
- Architecture
- Features
- Installation
- Quick Start
- Configuration in Your Application
- Configuration Reference
- Theming
- React Hooks API
- Components API
- TypeScript Support
- Troubleshooting
- Browser Support
- License
---
This package is the UI layer for the AsterMind Chatbot system. It provides pre-built React components and hooks for embedding a chatbot in your application.
```
Your Application
│
└── @astermind/chatbot-template (this package - UI components)
│
└── @astermind/cybernetic-chatbot-client (required - API client)
Important: @astermind/cybernetic-chatbot-client is automatically installed as a dependency. It provides:
- API Communication - Connects to your AsterMind backend
- Streaming Responses - SSE-based token-by-token message display
- Offline Fallback - Local RAG processing with IndexedDB cache
- Agentic Capabilities - DOM interactions (optional, tree-shakeable)
All configuration is done in your application code, not in node_modules:
| Configuration Method | Where to Set |
|---------------------|--------------|
| React Props | In your component: |.env
| Environment Variables | In your file |
| SSR Injection | In your server template |
| Global Object | In your HTML/JS before loading |
| Data Attributes | On your script tag |
---
- Embeddable Floating Chat Bubble - Position anywhere on the page (4 corners)
- React Components Library - 11 fully customizable components
- Vanilla JS Standalone Bundle - IIFE format with React bundled for non-React sites
- Full TypeScript Support - Complete type definitions exported
- Theming System - 20+ CSS custom properties for full visual customization
- AsterMind Backend Integration - Connects to /api/external/chat endpoints
- Streaming Responses - SSE-based token-by-token message display
- Source Citations - Collapsible source references with confidence levels
- Session Management - Automatic sessionId handling across conversations
- Offline Fallback - Local RAG processing when backend is unavailable
- Connection Status - Automatic online/offline/connecting/error states
When enabled, the chatbot can perform actions on your page:
- Navigation Actions - Navigate users to specific pages
- Form Filling - Auto-fill form fields with suggested values
- Element Clicking - Programmatically click buttons and links
- Modal Triggering - Open dialogs and modals
- Scrolling - Scroll to specific elements
- Element Highlighting - Draw attention to page elements
- Custom Action Handlers - Define your own action types
Agentic capabilities are tree-shakeable - they're only included in your bundle if you import and use them.
---
`bash`
npm install @astermind/chatbot-template
This automatically installs @astermind/cybernetic-chatbot-client as a dependency.
`html`
---
`tsx
import { ChatbotWidget } from '@astermind/chatbot-template';
import '@astermind/chatbot-template/styles';
function App() {
return (
apiKey="am_your-api-key"
position="bottom-right"
greeting="Hi! How can I help you today?"
/>
);
}
`
`html`
---
All configuration is done in your application code. The chatbot-template reads configuration from several sources in your project.
Option 1: Pass props directly
`tsx`
apiKey="am_your-api-key"
position="bottom-right"
/>
Option 2: Use environment variables
Create a .env file in your project root:
`envVite projects
VITE_ASTERMIND_RAG_API_KEY=am_your_api_key
VITE_ASTERMIND_RAG_API_SERVER_URL=https://api.astermind.ai
Then use the widget without explicit props:
`tsx
`$3
Option 1: Pass config to init()
`javascript
AsterMindChatbot.init({
apiKey: 'am_your_api_key',
apiUrl: 'https://api.astermind.ai',
position: 'bottom-right'
});
`Option 2: Global config object
`html
`Option 3: Script data attributes
`html
src="astermind-chatbot.min.js"
data-astermind-key="am_your_api_key"
data-astermind-url="https://api.astermind.ai"
>
`$3
For Next.js, Nuxt, or other SSR frameworks:
`html
`---
Configuration Reference
$3
The widget supports multiple configuration methods with this priority (highest to lowest):
1. Props / init() config - Direct configuration passed to the component or
init() function
2. Environment variables - VITE_ASTERMIND_RAG_API_KEY, REACT_APP_ASTERMIND_RAG_API_KEY
3. SSR-injected config - window.__ASTERMIND_CONFIG__
4. Global object - window.astermindConfig
5. Script data attributes - data-astermind-key, data-astermind-url$3
| Option | Type | Default | Description |
|--------|------|---------|-------------|
|
apiKey | string | (from env) | Your AsterMind API key (starts with am_). Falls back to environment variables. |
| apiUrl | string | 'https://api.astermind.ai' | Backend API URL. Falls back to environment variables. |
| throwOnMissingKey | boolean | true | Throw error if API key is missing. Set to false to log warning instead. |$3
| Option | Type | Default | Description |
|--------|------|---------|-------------|
|
position | 'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left' | 'bottom-right' | Widget position on screen |
| greeting | string | 'Hi! How can I help you today?' | Initial greeting message |
| placeholder | string | 'Type your message...' | Input placeholder text |
| headerTitle | string | 'AsterMind' | Chat window header title |
| headerSubtitle | string | 'AI Assistant' | Chat window header subtitle |
| defaultOpen | boolean | false | Start with chat window open |
| showPoweredBy | boolean | true | Show "Powered by AsterMind" badge |
| zIndex | number | 9999 | Z-index for the widget |$3
Customize appearance via the
theme object:`javascript
{
theme: {
primaryColor: '#4F46E5',
primaryHover: '#4338CA',
backgroundColor: '#ffffff',
surfaceColor: '#f3f4f6',
textColor: '#1f2937',
textMuted: '#6b7280',
borderColor: '#e5e7eb',
userBubbleBackground: '#4F46E5',
userBubbleText: '#ffffff',
botBubbleBackground: '#f3f4f6',
botBubbleText: '#1f2937',
widgetWidth: '380px',
widgetHeight: '75vh', // Default: 75% of viewport height
bubbleSize: '60px',
borderRadius: '12px',
fontFamily: "'Inter', system-ui, sans-serif",
fontSize: '14px',
shadow: '0 4px 20px rgba(0, 0, 0, 0.15)'
}
}
`$3
Enable agentic capabilities (powered by cybernetic-chatbot-client):
`javascript
{
agent: {
enabled: true,
confidenceThreshold: 0.8,
siteMap: [
{ path: '/products', name: 'Products', description: 'View products' },
{ path: '/contact', name: 'Contact', description: 'Contact us' }
],
customActions: {
openModal: async (params) => {
document.getElementById(params.modalId).showModal();
}
}
}
}
`$3
Configure offline behavior:
`javascript
{
fallback: {
enabled: true,
message: 'Working in offline mode. Some features may be limited.'
}
}
`$3
| Callback | Parameters | Description |
|----------|------------|-------------|
|
onReady | () | Called when widget is ready |
| onMessage | (message: ChatMessage) | Called on each message sent/received |
| onAction | (action: AgentAction) | Called when an agentic action occurs |
| onError | (error: Error) | Called when an error occurs |
| onToggle | (isOpen: boolean) | Called when widget opens/closes |---
Theming
$3
Override CSS variables in your stylesheet for quick customization:
`css
:root {
--astermind-primary: #10B981;
--astermind-primary-hover: #059669;
--astermind-background: #ffffff;
--astermind-surface: #f3f4f6;
--astermind-text: #1f2937;
--astermind-text-muted: #6b7280;
--astermind-border: #e5e7eb;
--astermind-user-bubble-bg: #10B981;
--astermind-user-bubble-text: #ffffff;
--astermind-bot-bubble-bg: #f3f4f6;
--astermind-bot-bubble-text: #1f2937;
--astermind-widget-width: 400px;
--astermind-widget-height: 75vh; / Default: 75% of viewport height (accepts px, vh, %) /
--astermind-bubble-size: 64px;
--astermind-border-radius: 16px;
--astermind-shadow: 0 8px 32px rgba(0, 0, 0, 0.12);
--astermind-font-family: 'Inter', system-ui, sans-serif;
--astermind-font-size: 14px;
}
`$3
All elements use the
astermind- prefix:| Class | Element |
|-------|---------|
|
.astermind-chatbot | Main container |
| .astermind-bubble | Floating trigger button |
| .astermind-window | Chat window |
| .astermind-header | Window header |
| .astermind-messages | Message list container |
| .astermind-message | Individual message |
| .astermind-message--user | User message modifier |
| .astermind-message--bot | Bot message modifier |
| .astermind-input | Input area |
| .astermind-status | Status indicator |
| .astermind-action-card | Action confirmation card |
| .astermind-sources | Source citations container |---
React Hooks API
$3
Direct API client access for custom implementations:
`tsx
import { useCybernetic } from '@astermind/chatbot-template';function MyComponent() {
const {
sendMessage, // Send a message (non-streaming)
sendMessageStream, // Send a message (streaming)
connectionStatus, // 'online' | 'offline' | 'connecting' | 'error'
isProcessing, // Whether a request is in progress
lastError, // Last error that occurred
sessionId, // Current session ID
clearSession, // Clear the current session
syncCache, // Sync cache for offline use
client // Underlying CyberneticClient instance
} = useCybernetic({
apiUrl: 'https://api.example.com',
apiKey: 'am_your-api-key'
});
const handleSend = async () => {
const response = await sendMessage('Hello!');
console.log(response.reply, response.sources);
};
}
`$3
Chat state management:
`tsx
import { useChat } from '@astermind/chatbot-template';function MyComponent() {
const {
messages, // Array of chat messages
addMessage, // Add a new message
updateMessage, // Update an existing message
clearMessages, // Clear all messages
pendingAction, // Currently pending agent action
setPendingAction // Set pending action
} = useChat();
}
`$3
Theme customization hook:
`tsx
import { useTheme } from '@astermind/chatbot-template';function MyComponent() {
const { theme, cssVariables } = useTheme({
primaryColor: '#10B981',
borderRadius: '16px'
});
return
...;
}
`$3
Auto-scroll behavior for message lists:
`tsx
import { useScrollToBottom } from '@astermind/chatbot-template';function MessageList({ messages }) {
const { containerRef, scrollToBottom } = useScrollToBottom();
return (
{messages.map(msg => )}
);
}
`---
Components API
All components are exported for custom compositions:
`tsx
import {
ChatbotWidget, // Main widget (includes bubble + window)
ChatBubble, // Floating trigger button
ChatWindow, // Chat window container
ChatHeader, // Window header with title/subtitle
ChatInput, // Message input with send button
MessageList, // Scrollable message container
MessageBubble, // Individual message bubble
ActionCard, // Agentic action confirmation card
SourceCitation, // Source reference component
StatusIndicator, // Connection status display
TypingIndicator // Typing/loading animation
} from '@astermind/chatbot-template';
`---
TypeScript Support
Full TypeScript support with exported types:
`typescript
import type {
// Template-specific types
AsterMindChatbotProps,
ChatbotTheme,
ChatMessage,
AgentAction,
ChatState,
WidgetPosition,
AgentConfig,
FallbackConfig,
SiteMapEntry,
VanillaInitConfig,
SendOptions, // Re-exported from @astermind/cybernetic-chatbot-client
CyberneticConfig,
CyberneticResponse,
CyberneticError,
Source,
ConnectionStatus,
ConfidenceLevel,
StreamCallbacks,
AskOptions,
CachedDocument,
CacheStatus,
AgenticConfig
} from '@astermind/chatbot-template';
// CyberneticClient class is also re-exported for advanced usage
import { CyberneticClient } from '@astermind/chatbot-template';
`---
Troubleshooting
$3
1. Ensure styles are imported:
import '@astermind/chatbot-template/styles'
2. Check that apiUrl and apiKey are provided
3. Verify the widget container has position: relative or is in the document flow$3
1. Check that your
apiUrl is correct and accessible
2. Verify your API key is valid and has the correct permissions
3. Check browser console for CORS errors - ensure your backend allows the origin$3
1. Verify your backend supports the
/api/external/chat/stream endpoint
2. Check that SSE is not being blocked by proxies or firewalls
3. Ensure Content-Type: text/event-stream header is set on responses$3
1. Confirm
agent.enabled is set to true
2. Check that actions meet the confidenceThreshold
3. Verify custom action handlers are properly defined$3
1. Ensure the CSS file is loaded before the JS
2. Check for CSS specificity conflicts with your existing styles
3. Use
!important or increase specificity if needed---
Browser Support
| Browser | Version |
|---------|---------|
| Chrome | 80+ |
| Firefox | 75+ |
| Safari | 13+ |
| Edge | 80+ |
The standalone bundle includes necessary polyfills for broader compatibility.
---
Build Outputs
| File | Format | Description |
|------|--------|-------------|
|
astermind-chatbot.esm.js | ESM | ES Module for bundlers (tree-shakeable) |
| astermind-chatbot.umd.js | UMD | Universal Module Definition |
| astermind-chatbot.min.js | IIFE | Standalone bundle with React included |
| astermind-chatbot.css` | CSS | Compiled and minified styles |---
MIT License - see LICENSE for details.
Built with care by the AsterMind team.