aspirechat
Version:
A highly customizable React chatbot component with extensive configuration options
465 lines (400 loc) • 14.8 kB
Markdown
# AspireChat
A highly customizable React chatbot component with extensive configuration options for modern web applications.
[](https://www.npmjs.com/package/aspirechat)
[](https://github.com/aspiredev/aspirechat/blob/main/LICENSE)
## Features
- 🎨 **Highly Customizable**: Customize every aspect of the chatbot UI through extensive theme options
- 🔌 **Plug and Play**: Easy to integrate with any React application
- 📱 **Responsive**: Works seamlessly across devices and screen sizes
- 🔗 **API Integration**: Connect to any backend API for dynamic responses
- 🧩 **Plugin System**: Extend functionality through custom plugins
- 🌓 **Dark Mode Support**: Built-in dark theme and custom theme options
- 📊 **Button-Based Flows**: Guide users through conversations with predefined buttons
- 💬 **Typing Indicators**: Natural typing indicators for a more engaging experience
- 🔄 **Persistent Chat**: Option to persist chat history between sessions
## Installation
```bash
npm install aspirechat
# or
yarn add aspirechat
```
## Quick Start
### Button-Based Flows
```jsx
import React from "react";
import { Chatbot } from "aspirechat";
import { ChatContextProvider } from "aspirechat";
const App = () => {
// Define your chat flows
const chatFlows = {
welcome: {
id: "welcome",
messages: [
{
text: "Welcome to our support chatbot! How can I help you today?",
type: "bot",
},
],
options: [
{
id: "1",
text: "Product Information",
value: "",
nextFlow: "products",
},
{
id: "2",
text: "Pricing Plans",
value: "",
nextFlow: "pricing",
},
{
id: "3",
text: "Contact Support",
value: "",
nextFlow: "contact",
},
],
},
products: {
id: "products",
messages: [
{
text: "We offer the following products:",
type: "bot",
},
{
text: "<ul><li>Product A - Analytics Suite</li><li>Product B - CRM Solution</li><li>Product C - Marketing Automation</li></ul>",
type: "bot",
html: true,
},
],
options: [
{
id: "1",
text: "Tell me about Product A",
value: "",
nextFlow: "productA",
},
{
id: "2",
text: "Tell me about Product B",
value: "",
nextFlow: "productB",
},
{ id: "3", text: "Back to menu", value: "", nextFlow: "welcome" },
],
},
pricing: {
id: "pricing",
messages: [
{
text: "Our pricing starts at $49/month for the basic plan.",
type: "bot",
},
],
options: [
{
id: "1",
text: "See pricing details",
value: "Here's our detailed pricing structure...",
nextFlow: null,
},
{ id: "2", text: "Back to menu", value: "", nextFlow: "welcome" },
],
},
contact: {
id: "contact",
messages: [
{
text: "You can reach our support team at support@example.com or by phone at 555-123-4567.",
type: "bot",
},
],
options: [
{
id: "1",
text: "Email Support",
value: "I'll open your email client to contact support.",
nextFlow: null,
},
{
id: "2",
text: "Call Support",
value: "Connecting you with our support team...",
nextFlow: null,
},
{ id: "3", text: "Back to menu", value: "", nextFlow: "welcome" },
],
},
};
return (
<div className="App">
<header className="App-header">
<h1>My Website</h1>
</header>
<ChatContextProvider
initialConfig={{
headerTitle: "Support Bot",
initiallyOpen: true,
}}
initialOptions={{
flows: chatFlows,
initialFlow: "welcome",
}}
>
<Chatbot />
</ChatContextProvider>
</div>
);
};
export default App;
```
## Advanced Configuration
AspireChat is designed to be highly customizable. Below are some examples of more advanced configurations.
### Connecting to an API endpoint
```jsx
import { Chatbot } from "aspirechat";
const App = () => {
const api = {
endpoint: "https://api.example.com/chat",
headers: {
Authorization: "Bearer YOUR_API_KEY",
},
transformRequest: (message) => ({
query: message.text,
userId: "user-123",
}),
transformResponse: (data) => ({
text: data.response,
type: "bot",
}),
};
return <Chatbot api={api} />;
};
```
### Custom Theme
```jsx
import { Chatbot, darkTheme } from "aspirechat";
const App = () => {
// Start with the built-in dark theme and customize it
const customTheme = {
...darkTheme,
primary: "#6d28d9", // purple-700
secondary: "#8b5cf6", // purple-500
userBubbleBackground: "#6d28d9", // purple-700
userBubbleText: "#ffffff",
botBubbleBackground: "#4c1d95", // purple-900
botBubbleText: "#ffffff",
fontFamily: "'Poppins', sans-serif",
};
return (
<Chatbot
config={{
theme: customTheme,
headerTitle: "Custom Support Bot",
}}
/>
);
};
```
### Customizing Chat Position
```jsx
import { Chatbot } from "aspirechat";
const App = () => {
return (
<Chatbot
config={{
position: {
placement: "bottom-left", // "top-left", "top-right", "bottom-left", "bottom-right"
offsetX: "30px",
offsetY: "30px",
},
width: "400px",
maxHeight: "700px",
}}
/>
);
};
```
### Persistent Chat History
```jsx
import { Chatbot } from "aspirechat";
const App = () => {
return (
<Chatbot
config={{
persistHistory: true,
persistKey: "my-app-chat-history",
}}
/>
);
};
```
### Mobile Configuration
```jsx
import { Chatbot } from "aspirechat";
const App = () => {
return (
<Chatbot
config={{
mobile: {
fullScreen: true, // Full screen on mobile
bottomOffset: "60px", // Space for bottom navigation bar
},
fullScreenBreakpoint: "768px", // Switch to full screen below this width
}}
/>
);
};
```
## Using with Next.js
AspireChat is compatible with Next.js, but requires proper client component setup:
```jsx
"use client"; // This directive is important!
import React from "react";
import { Chatbot, ChatContextProvider } from "aspirechat";
export default function ChatWidget() {
return (
<ChatContextProvider
initialConfig={{
headerTitle: "Support Bot",
initiallyOpen: true,
}}
initialOptions={{
flows: {
welcome: {
id: "welcome",
messages: [
{
text: "Welcome! How can I help you?",
type: "bot",
},
],
options: [
{
id: "1",
text: "Learn More",
value: "Here's some information...",
nextFlow: null,
},
],
},
},
initialFlow: "welcome",
}}
>
<Chatbot />
</ChatContextProvider>
);
}
```
**Important**: Make sure to only use AspireChat components in client components (marked with 'use client').
## API Reference
### `<Chatbot>` Props
| Prop | Type | Description |
| ---------------------- | --------- | --------------------------------------------- |
| `config` | `object` | Configuration options for the chatbot |
| `handlers` | `object` | Event handlers for various chatbot actions |
| `responses` | `array` | Array of predefined response patterns |
| `api` | `object` | API configuration for connecting to a backend |
| `plugins` | `array` | Custom plugins to extend functionality |
| `className` | `string` | Additional CSS class names |
| `disableDefaultStyles` | `boolean` | Disable default styled-components styles |
### Configuration Options
#### Basic Configuration
| Option | Type | Default | Description |
| -------------------- | -------------------- | ------------------- | -------------------------------------------------------- |
| `headerTitle` | `string` | "Chat Support" | Title displayed in the header |
| `welcomeMessage` | `string` or `object` | undefined | Initial message sent by the bot |
| `placeholderText` | `string` | "Type a message..." | Placeholder text for the input field |
| `initiallyOpen` | `boolean` | `false` | Whether the chat window should be open on initial render |
| `showMinimizeButton` | `boolean` | `true` | Display minimize button in the header |
| `showCloseButton` | `boolean` | `true` | Display close button in the header |
| `logo` | `string` | undefined | URL to the logo image displayed in the header |
#### Appearance
| Option | Type | Default | Description |
| ---------------- | --------- | ------------------------------- | -------------------------------------------- |
| `theme` | `object` | `defaultTheme` | Theme configuration object |
| `position` | `object` | `{ placement: 'bottom-right' }` | Positioning of the chat window |
| `width` | `string` | "350px" | Width of the chat window |
| `height` | `string` | undefined | Height of the chat window |
| `maxHeight` | `string` | "600px" | Maximum height of the chat window |
| `minHeight` | `string` | "300px" | Minimum height of the chat window |
| `roundedCorners` | `boolean` | `true` | Use rounded corners for the chat window |
| `boxShadow` | `boolean` | `true` | Apply box shadow to the chat window |
| `floatingButton` | `object` | undefined | Configuration for the floating toggle button |
#### Behavior
| Option | Type | Default | Description |
| ------------------------ | --------- | --------- | ------------------------------------------------- |
| `enableTypingIndicator` | `boolean` | `true` | Show typing indicator when the bot is "typing" |
| `typingIndicatorTimeout` | `number` | 1000 | Duration of the typing indicator in milliseconds |
| `autoFocus` | `boolean` | `true` | Auto focus the input field when the chat opens |
| `persistHistory` | `boolean` | `false` | Persist chat history in localStorage |
| `persistKey` | `string` | undefined | Key for localStorage when persisting chat history |
| `showTimestamp` | `boolean` | `true` | Show timestamps for messages |
| `timestampFormat` | `string` | "HH:mm" | Format for timestamps (HH:mm:ss) |
| `enableAutoScroll` | `boolean` | `true` | Auto scroll to the latest message |
### Event Handlers
| Handler | Parameters | Description |
| --------------- | ------------------------ | ---------------------------------------- |
| `onMessage` | `(message: ChatMessage)` | Called when a message is added |
| `onSendMessage` | `(text: string)` | Called when a user sends a message |
| `onOpen` | none | Called when the chat window is opened |
| `onClose` | none | Called when the chat window is closed |
| `onMinimize` | none | Called when the chat window is minimized |
| `onMaximize` | none | Called when the chat window is maximized |
| `onFileUpload` | `(file: File)` | Called when a file is uploaded |
| `onError` | `(error: Error)` | Called when an error occurs |
## Creating Custom Plugins
You can extend AspireChat's functionality with custom plugins:
```jsx
import { Chatbot } from "aspirechat";
// Analytics plugin example
const analyticsPlugin = {
id: "analytics",
name: "Analytics Tracker",
initialize: (chat) => {
// Plugin initialization
console.log("Analytics plugin initialized");
},
middleware: (message, next) => {
// Track all messages
if (message.type === "user") {
console.log("User message tracked:", message.text);
// You could send to analytics service here
}
// Continue processing
next();
},
destroy: () => {
console.log("Analytics plugin destroyed");
},
};
const App = () => {
return <Chatbot plugins={[analyticsPlugin]} />;
};
```
## TypeScript Support
AspireChat is built with TypeScript and exports all types for excellent developer experience:
```tsx
import { Chatbot, ChatConfig, ChatResponse, ChatAPI } from "aspirechat";
const config: ChatConfig = {
headerTitle: "TypeScript Chat",
welcomeMessage: "Welcome to our TypeScript-powered chat!",
};
const responses: ChatResponse[] = [
{
pattern: /hello/i,
response: "Hi there!",
},
];
const api: ChatAPI = {
endpoint: "/api/chat",
};
const App = () => {
return <Chatbot config={config} responses={responses} api={api} />;
};
```
## License
MIT © [AspireDev](https://aspiredev.in/)