React AI Chat Widget

A plug-and-play React chatbot component supporting multiple AI providers (OpenAI, Anthropic, Mistral). Zero UI framework dependencies, fully typed with TypeScript, and highly customizable.

Features

Multiple AI Providers: OpenAI, Anthropic (Claude), and Mistral out of the box
Zero UI Dependencies: Pure CSS with CSS variables for easy theming
TypeScript Support: Fully typed with exported types
Customizable Position: Place the chatbot in any corner of the screen
Theming: Light/dark/auto themes with custom color support
Markdown Support: Renders markdown in AI responses
Responsive: Works on mobile and desktop
Callbacks: Hooks for message events and errors

Installation

npm install react-ai-chat-widget

Quick Start

import { Chatbot } from 'react-ai-chat-widget';
import 'react-ai-chat-widget/styles';

function App() {
  return (
    <Chatbot
      aiConfig={{
        provider: 'openai',
        apiKey: 'your-api-key',
        model: 'gpt-4',
        systemPrompt: 'You are a helpful assistant.',
      }}
    />
  );
}

Configuration

AI Configuration

Prop	Type	Required	Description
`provider`	`'openai' \| 'anthropic' \| 'mistral'`	Yes	AI provider to use
`apiKey`	`string`	Yes	API key for the provider
`model`	`string`	No	Model to use (defaults vary by provider)
`systemPrompt`	`string`	No	System prompt for context
`maxTokens`	`number`	No	Maximum tokens in response (default: 1024)
`temperature`	`number`	No	Response randomness 0-1 (default: 0.7)

Component Props

Prop	Type	Default	Description
`position`	`'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'`	`'bottom-right'`	Position on screen
`offsetX`	`number`	`24`	Horizontal offset in pixels
`offsetY`	`number`	`24`	Vertical offset in pixels
`chatWidth`	`number \| string`	`400`	Chat window width
`chatHeight`	`number \| string`	`'70vh'`	Chat window height
`toggleIcon`	`ReactNode`	Chat bubble icon	Custom toggle button icon
`toggleLabel`	`string`	-	Text label for toggle button
`showToggleLabel`	`boolean`	`true`	Show/hide toggle label
`theme`	`'light' \| 'dark' \| 'auto'`	`'light'`	Color theme
`themeConfig`	`ThemeConfig`	-	Custom theme colors
`welcomeMessage`	`string \| string[]`	-	Welcome message (random if array)
`placeholder`	`string`	`'Type your message...'`	Input placeholder
`closeOnClickOutside`	`boolean`	`true`	Close when clicking outside
`persistMessages`	`boolean`	`false`	Keep messages on close
`loadingText`	`string`	`'Thinking...'`	Loading indicator text
`onOpen`	`() => void`	-	Called when chat opens
`onClose`	`() => void`	-	Called when chat closes
`onMessageSent`	`(message: string) => void`	-	Called when user sends message
`onMessageReceived`	`(message: string) => void`	-	Called when AI responds
`onError`	`(error: Error) => void`	-	Called on error

AI Provider Examples

OpenAI

<Chatbot
  aiConfig={{
    provider: 'openai',
    apiKey: process.env.REACT_APP_OPENAI_KEY,
    model: 'gpt-4', // or 'gpt-3.5-turbo'
  }}
/>

Anthropic (Claude)

<Chatbot
  aiConfig={{
    provider: 'anthropic',
    apiKey: process.env.REACT_APP_ANTHROPIC_KEY,
    model: 'claude-3-opus-20240229', // or 'claude-3-sonnet', 'claude-3-haiku'
  }}
/>

Note: Anthropic API requires CORS headers. For browser usage, you may need a proxy server or use their official SDK with server-side calls.

Mistral

<Chatbot
  aiConfig={{
    provider: 'mistral',
    apiKey: process.env.REACT_APP_MISTRAL_KEY,
    model: 'mistral-large-latest', // or 'mistral-small-latest'
  }}
/>

Theming

CSS Variables

Customize the appearance using CSS variables:

:root {
  --chatbot-primary: #6366f1;
  --chatbot-bg: #ffffff;
  --chatbot-text: #1f2937;
  --chatbot-user-bubble: #6366f1;
  --chatbot-user-text: #ffffff;
  --chatbot-assistant-bubble: #f3f4f6;
  --chatbot-assistant-text: #1f2937;
  --chatbot-border-radius: 12px;
  --chatbot-font-family: system-ui, sans-serif;
}

Custom Theme Object

<Chatbot
  aiConfig={config}
  themeConfig={{
    primaryColor: '#10b981',
    backgroundColor: '#f0fdf4',
    userBubbleColor: '#10b981',
    assistantBubbleColor: '#d1fae5',
    borderRadius: 16,
  }}
/>

Dark Theme

<Chatbot
  aiConfig={config}
  theme="dark"
/>

Auto Theme (System Preference)

<Chatbot
  aiConfig={config}
  theme="auto"
/>

Customizing Size

Control the chat window dimensions with chatWidth and chatHeight:

<Chatbot
  aiConfig={config}
  chatWidth={380}      // pixels
  chatHeight={500}     // pixels
/>

You can also use string values for responsive sizing:

<Chatbot
  aiConfig={config}
  chatWidth="90vw"     // viewport width
  chatHeight="80vh"    // viewport height
/>

Custom Toggle Button

With Icon Library (react-icons)

import { Chatbot } from 'react-ai-chat-widget';
import { FaRobot } from 'react-icons/fa';

<Chatbot
  aiConfig={config}
  toggleIcon={<FaRobot size={24} />}
  toggleLabel="Ask AI"
/>

With Custom SVG Icon

<Chatbot
  aiConfig={config}
  toggleLabel="Ask Me"
  toggleIcon={
    <svg
      width="24"
      height="24"
      viewBox="0 0 24 24"
      fill="none"
      stroke="currentColor"
      strokeWidth="2"
      strokeLinecap="round"
      strokeLinejoin="round"
    >
      <path d="M12 3l1.5 4.5L18 9l-4.5 1.5L12 15l-1.5-4.5L6 9l4.5-1.5L12 3z" />
      <path d="M5 19l1 3 1-3 3-1-3-1-1-3-1 3-3 1 3 1z" />
    </svg>
  }
/>

With Emoji

<Chatbot
  aiConfig={config}
  toggleIcon={<span style={{ fontSize: '24px' }}>🤖</span>}
  toggleLabel="Chat"
/>

Label Only (No Custom Icon)

<Chatbot
  aiConfig={config}
  toggleLabel="Need Help?"
/>

Welcome Messages

Single Message

<Chatbot
  aiConfig={config}
  welcomeMessage="Hi! How can I help you today?"
/>

Random from Array

<Chatbot
  aiConfig={config}
  welcomeMessage={[
    "Hi! How can I help?",
    "Hello! What can I do for you?",
    "Hey there! Ask me anything!",
  ]}
/>

Event Callbacks

<Chatbot
  aiConfig={config}
  onOpen={() => console.log('Chat opened')}
  onClose={() => console.log('Chat closed')}
  onMessageSent={(msg) => console.log('User:', msg)}
  onMessageReceived={(msg) => console.log('AI:', msg)}
  onError={(err) => console.error('Error:', err)}
/>

TypeScript

All types are exported for use in your application:

import type {
  ChatbotProps,
  AIConfig,
  AIProvider,
  ThemeConfig,
  Message,
} from 'react-ai-chat-widget';

Advanced Usage

Using Hooks Directly

For custom implementations, you can use the hooks directly:

import { useChat } from 'react-ai-chat-widget';

function CustomChat() {
  const { messages, isLoading, sendMessage, addMessage } = useChat({
    aiConfig: {
      provider: 'openai',
      apiKey: 'your-key',
    },
  });

  // Build your own UI
}

Using Providers Directly

import { getProvider } from 'react-ai-chat-widget';

const provider = getProvider({ provider: 'openai', apiKey: 'your-key' });
const response = await provider.sendMessage(
  [{ role: 'user', content: 'Hello' }],
  config
);

Real-World Example: Portfolio Assistant

Here's a complete example of using the chat widget as a portfolio assistant that answers questions about your skills and experience:

"use client"; // For Next.js App Router

import { Chatbot } from "react-ai-chat-widget";
import "react-ai-chat-widget/styles";

// Import your portfolio data
import { experience, skills, technologies, socialLinks } from "@/lib/data";

// Build dynamic system prompt from your data
const systemPrompt = `You are a helpful AI assistant on my portfolio website.

## About Me
Full Stack Developer with 5+ years of experience specializing in Node.js, React, and cloud technologies.

## Work Experience
${experience.map((exp) => `- ${exp.company}: ${exp.designation}`).join("\n")}

## Technologies
${technologies.map((t) => t.name).join(", ")}

## Services
${skills.map((s) => `- ${s.service}`).join("\n")}

## Contact
- Email: ${socialLinks.email}
- LinkedIn: ${socialLinks.linkedin}

Be friendly, professional, and encourage visitors to reach out for collaboration.`;

export function PortfolioChat() {
  return (
    <Chatbot
      aiConfig={{
        provider: "mistral",
        apiKey: process.env.NEXT_PUBLIC_MISTRAL_API_KEY || "",
        model: "mistral-small-latest",
        systemPrompt,
      }}
      position="bottom-right"
      theme="dark"
      chatWidth={380}
      chatHeight={500}
      welcomeMessage="Hi! I'm here to help you learn more about my work and skills. What would you like to know?"
      placeholder="Ask me anything..."
      themeConfig={{ primaryColor: "#8b5cf6" }}
      toggleLabel="askMe"
      toggleIcon={
        <svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
          <path d="M12 3l1.5 4.5L18 9l-4.5 1.5L12 15l-1.5-4.5L6 9l4.5-1.5L12 3z" />
        </svg>
      }
    />
  );
}

Then add it to your layout:

// app/layout.tsx
import { PortfolioChat } from "@/components/portfolio-chat";

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <PortfolioChat />
      </body>
    </html>
  );
}

This approach keeps your chatbot's knowledge in sync with your portfolio data automatically!

Why This Package?

Feature	react-ai-chat-widget	Most Alternatives
AI Providers	Built-in OpenAI, Anthropic, Mistral	Usually require custom integration
Dependencies	Zero UI framework deps (pure CSS)	Often require MUI, styled-components
Setup	Single component, pass API key & go	Often need backend setup
Styling	CSS variables for easy theming	Many use CSS-in-JS
Bundle Size	Lightweight (~25KB)	Often larger due to dependencies

Browser Support

Chrome (latest)
Firefox (latest)
Safari (latest)
Edge (latest)

License

MIT

Contributing

See CONTRIBUTING.md for contribution guidelines.

Happy coding!

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
__tests__		__tests__
src		src
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
rollup.config.js		rollup.config.js
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

React AI Chat Widget

Features

Installation

Quick Start

Configuration

AI Configuration

Component Props

AI Provider Examples

OpenAI

Anthropic (Claude)

Mistral

Theming

CSS Variables

Custom Theme Object

Dark Theme

Auto Theme (System Preference)

Customizing Size

Custom Toggle Button

With Icon Library (react-icons)

With Custom SVG Icon

With Emoji

Label Only (No Custom Icon)

Welcome Messages

Single Message

Random from Array

Event Callbacks

TypeScript

Advanced Usage

Using Hooks Directly

Using Providers Directly

Real-World Example: Portfolio Assistant

Why This Package?

Browser Support

License

Contributing

About

Topics

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages