AspireChat

A highly customizable React chatbot component with extensive configuration options for modern web applications.

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

npm install aspirechat
# or
yarn add aspirechat

Quick Start

Button-Based Flows

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 [email protected] 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

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

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

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

import { Chatbot } from "aspirechat";

const App = () => {
  return (
    <Chatbot
      config={{
        persistHistory: true,
        persistKey: "my-app-chat-history",
      }}
    />
  );
};

Mobile Configuration

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:

"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:

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:

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