react-chat-ai-widget

🤖 React Chat AI Widget

React Chat AI Widget is a plug-and-play React component that lets you embed a fully customizable, intelligent chatbot into your app — with zero backend setup required.

It supports Hugging Face or Replicate APIs for real-time AI responses, making it ideal for customer support, onboarding, FAQs, smart documentation bots, and more.

✨ Features

• 🤖 AI chatbot powered by Hugging Face or Replicate
• ⚡ No backend needed – fully client-side with secure token proxy
• 🎯 Behavior-aware via use cases (e.g. support, documentation, etc.)
• 🧩 Built with React + TypeScript
• 🎨 Fully customizable UI and styles
• 🔐 Tokens are secured — never exposed to the client
• 🧪 Ready for testing with Vitest and Cypress

📦 Installation

npm install react-chat-ai-widget

import { ChatWidget } from "react-chat-ai-widget";

<ChatWidget
  title="InsightFlow"
  direction="left" // or "right" (default)
  huggingface="YOUR_HUGGINGFACE_TOKEN"
  // replicate="YOUR_REPLICATE_TOKEN" (use one or the other)
  config={{
    temperature: 0.7,
    max_tokens: 200,
    top_p: 0.9,
    frequency_penalty: 0.5,
    model: "microsoft/DialoGPT-large",
    stop_sequences: ["\n\n", "Human:", "Bot:"],
  }}
  //replicate and huggingFace has different config
  data={{
    useCase: "customer-support",
    questions: [
      {
        question: "What are your business hours?",
        answer: "We’re open Monday to Friday from 10am to 4pm.",
        category: "general",
        confidence: 0.98,
      },
      {
        question: "Who wrote Don Quixote?",
        answer: "Miguel de Cervantes.",
        category: "literature",
        confidence: 0.92,
      },
    ],
  }}
  chatStyles={{}}
  formStyles={{
    inputStyles: {},
    buttonStyles: {},
    formStyles: {},
  }}
/>;

🎨 Styling

To ensure the ChatWidget renders properly, import the style file in your main entry point:

import "react-chat-ai-widget/dist/React-Chat-Widget.css";

You can customize the layout using either class names or inline style objects.

🧩 Component Props

Prop	Type	Required	Description
title	string	No	Chat header title. Defaults to "AI Assistant".
data	object	Yes	Contains pre-defined Q&A and optional use case.
huggingface	string	Conditional	Your Hugging Face API token. Do not use with replicate.
replicate	string	Conditional	Your Replicate API token. Do not use with huggingface.
direction	string	No	"left" or "right". Default is "right".
chatClassName	string	No	Custom class for chat container.
chatStyles	object	No	Inline styles for chat container.
headerClassName	string	No	Custom class for header.
headerStyles	object	No	Inline styles for header section.
formStyles	object	No	Object containing style overrides for the form.
└ inputStyles	object	No	Styles for the input field.
└ buttonStyles	object	No	Styles for the submit button.
└ formStyles	object	No	Styles for the entire form container.
config	object	No	Configuration for the AI service.

🧠 Data Format

Define a list of questions and answers the chatbot can use, with an optional useCase to control tone or behavior.

{
  useCase: "qa-bot", // or "customer-support", "documentation", "strict-compliance"
  questions: [
    {
      question: "Your question here?",
      answer: "The chatbot response.",
      category: "general",
      confidence: 0.85 // Value between 0 and 1
    },
    // Add as many as needed
  ]
}

Supported useCase values

• "customer-support": Friendly, helpful support tone
• "documentation": Technical, concise answers
• "qa-bot": Default Q&A with open logic
• "strict-compliance": Controlled, policy-aware responses

🔐 Token Security

Your API tokens are never exposed to the client.

• ✅ Hugging Face or Replicate tokens are sent securely through a proxy
• ✅ No direct client-to-model communication
• ✅ Fully encrypted and safe

🖼️ Chat Preview

Chat aligned left	Chat aligned right

🔧 Advanced Model Configuration

Take full control of your AI's behavior with comprehensive model customization options:

🎛️ Core Parameters

• temperature (0.0 - 2.0) - Controls response creativity and randomness

• 0.1 = Focused, deterministic responses

• 0.7 = Balanced creativity (recommended)

• 1.5 = Highly creative, varied outputs

• max_tokens (1 - 4096) - Maximum response length

• 50 = Short, concise answers

• 150 = Standard responses

• 500+ = Detailed, comprehensive replies

🎯 Fine-Tuning Options

• top_p (0.0 - 1.0) - Nucleus sampling for response diversity
• frequency_penalty (-2.0 - 2.0) - Reduces repetitive content
• presence_penalty (-2.0 - 2.0) - Encourages topic exploration
• stop_sequences - Custom stop words to control response endings
• model - Choose specific AI models for different capabilities

💡 Example Configuration

config={{
 temperature: 0.7,
 max_tokens: 200,
 top_p: 0.9,
 frequency_penalty: 0.5,
 model: "microsoft/DialoGPT-large",
 stop_sequences: ["\n\n", "Human:", "Bot:"]
}}

⚠️ Notes

• Do not use both huggingface and replicate props at the same time.

• You must import the CSS file for the widget to render correctly.

• The chatStyles and headerStyles props override any class-based styles (chatClassName, headerClassName).

  ⚠️ Important Note for Hugging Face Users If you're using this chatbot with Hugging Face and plan to enable mode (or similar streaming indicators), make sure to set max_tokens to at least 500 in your configuration.

  is necessary because consumes a significant number of tokens during generation. If max_tokens is too low, the assistant's response might get cut off or fail to generate properly.

🧪 Testing

• Includes support for unit and UI testing using Vitest and Cypress.
• Example test commands:

npm run test        # Vitest
npm run dev         # Local dev mode
npm run lint        # ESLint
npm run build       # Production build

🚧 Upcoming Features

🛍️ Product Recommendation Engine

• The chatbot will soon be able to recommend products based on user questions, behavior, and preferences in real time.

• 🌐 Multi-language support

• 🌎 Internationalization (i18n)

• 📊 Analytics Dashboard (Q3 2024) Conversation insights and performance metrics.

• 🔗 Integration Plugins (Q4 2024) Direct integrations with popular platforms (Shopify, WordPress, etc.).

📄 License

MIT © Jorge Ernesto