@calq/neura-chat-widget
Version:
NeuraChat embedable script to insert chat widget
228 lines (170 loc) • 5.92 kB
Markdown
# NeuraChat Widget
[](https://badge.fury.io/js/@calq%2Fneura-chat-widget)
[](https://opensource.org/licenses/MIT)
A lightweight, embeddable chat widget for integrating NeuraChat AI assistant into your website or web application. Supports both inline and floating bubble modes with customizable styling and positioning.
## Features
- 🚀 **Easy Integration** - Simple JavaScript API with minimal setup
- 💬 **Two Display Modes** - Inline embedding or floating bubble widget
- 🎨 **Customizable** - Configurable colors, positioning, and styling
- 📱 **Responsive** - Works seamlessly on desktop and mobile devices
- ⚡ **Lightweight** - Minimal footprint with no external dependencies
- 🔧 **TypeScript Support** - Full TypeScript definitions included
## Installation
### Via NPM
```bash
npm install neura-chat-widget
```
### Via CDN
```html
<script src="https://unpkg.com/neura-chat-widget@latest/dist/widget.js"></script>
```
## Quick Start
### Bubble Widget (Floating)
Create a floating chat bubble that appears on your website:
```html
<!DOCTYPE html>
<html>
<head>
<script src="https://unpkg.com/neura-chat-widget@latest/dist/widget.js"></script>
</head>
<body>
<script>
NeuraChat.createBubbleWidget({
baseUrl: "https://widget.neurachat.ai",
widgetId: "your-widget-id",
position: "right"
});
</script>
</body>
</html>
```
### Inline Widget (Embedded)
Embed the chat widget directly into a container element:
```html
<!DOCTYPE html>
<html>
<head>
<script src="https://unpkg.com/neura-chat-widget@latest/dist/widget.js"></script>
</head>
<body>
<div id="chat-container" style="width: 400px; height: 600px;"></div>
<script>
NeuraChat.createInlineWidget({
baseUrl: "https://widget.neurachat.ai",
widgetId: "your-widget-id",
element: "chat-container"
});
</script>
</body>
</html>
```
## API Reference
### `createBubbleWidget(options)`
Creates a floating bubble chat widget.
**Parameters:**
- `options` (Object): Configuration options
- `baseUrl` (string): The base URL of your NeuraChat instance
- `widgetId` (string): Your unique widget identifier
- `position` (string): Position of the bubble - `"left"` or `"right"` (default: `"right"`)
**Returns:**
- `NeuraChatBubbleWidgetInstance`: Widget instance with methods
- `destroy()`: Remove the widget from the page
- `toggle()`: Programmatically toggle the widget open/closed
**Example:**
```javascript
const widget = NeuraChat.createBubbleWidget({
baseUrl: "https://widget.neurachat.ai",
widgetId: "your-widget-id",
position: "left"
});
// Toggle the widget programmatically
widget.toggle();
// Remove the widget
widget.destroy();
```
### `createInlineWidget(options)`
Creates an inline chat widget embedded in a container.
**Parameters:**
- `options` (Object): Configuration options
- `baseUrl` (string): The base URL of your NeuraChat instance
- `widgetId` (string): Your unique widget identifier
- `element` (HTMLElement | string): Container element or element ID
**Returns:**
- `NeuraChatInlineWidgetInstance`: Widget instance with methods
- `destroy()`: Remove the widget from the container
**Example:**
```javascript
const widget = NeuraChat.createInlineWidget({
baseUrl: "https://widget.neurachat.ai",
widgetId: "your-widget-id",
element: document.getElementById("chat-container")
});
// Remove the widget
widget.destroy();
```
## Advanced Usage
### ES6 Modules
If you're using a module bundler like Webpack or Vite:
```javascript
import { createBubbleWidget, createInlineWidget } from 'neura-chat-widget';
// Create bubble widget
const bubbleWidget = createBubbleWidget({
baseUrl: "https://widget.neurachat.ai",
widgetId: "your-widget-id",
position: "right"
});
// Create inline widget
const inlineWidget = createInlineWidget({
baseUrl: "https://widget.neurachat.ai",
widgetId: "your-widget-id",
element: "#chat-container"
});
```
### TypeScript
The package includes TypeScript definitions:
```typescript
import {
createBubbleWidget,
createInlineWidget,
NeuraChatBubbleWidgetOptions,
NeuraChatInlineWidgetOptions
} from 'neura-chat-widget';
const bubbleOptions: NeuraChatBubbleWidgetOptions = {
baseUrl: "https://widget.neurachat.ai",
widgetId: "your-widget-id",
position: "right"
};
const widget = createBubbleWidget(bubbleOptions);
```
## Styling and Customization
The widget automatically adapts to your website's theme and supports custom accent colors through CSS custom properties:
```css
:root {
--neura-chat-widget-accent-color: #your-brand-color;
}
```
### CSS Classes
The widget uses the following CSS classes that you can style:
- `.neura-chat-widget` - Base widget container
- `.neura-chat-widget-bubble` - Bubble widget container
- `.neura-chat-widget-inline` - Inline widget container
- `.neura-chat-widget__button` - Bubble toggle button
- `.neura-chat-widget__wrapper` - Widget content wrapper
- `.neura-chat-widget__iframe` - Chat iframe
## Browser Support
- Chrome 60+
- Firefox 55+
- Safari 11+
- Edge 79+
## Getting Your Widget ID
1. Sign up at [NeuraChat](https://neurachat.ai)
2. Create a new chat widget in your dashboard
3. Copy the widget ID from the integration settings
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Support
- 📧 Email: [support@neurachat.ai](mailto:support@neurachat.ai)
- 🐛 Issues: [GitHub Issues](https://github.com/Calq-dev/neura-chat-widget/issues)
- 📖 Documentation: [NeuraChat Docs](https://docs.neurachat.ai)