chatbot-assistant-ui

A premium, interactive robot chatbot mascot — built as a framework-agnostic React component with pure SVG, CSS animations, and zero heavy dependencies.

✨ Features

| Feature | Description | |---|---| | 🎯 Cursor-tracking eyes | Pupils follow the user's mouse in real-time | | ❤️ 7 Emotion types | hearts, surprise, laugh, dizzy, cool, sad, angry | | 💥 Click reactions | Click to cycle through expressions with particle bursts | | ❤️ Heart particles | Floating ❤️ particles on love expression | | ⭐ Star-burst eyes | SVG star polygons for surprise | | 😢 Teardrop animation | Animated tears for sad expression | | 😠 Angry brows + teeth | Angled eyebrows and snarl mouth | | 🤖 Robotic design | Bolts, ear LEDs, power core, antenna signals, joints | | 🌙 Light/Dark themes | Full theme support via CSS variables | | 📏 Scalable | Set any size via props | | ♿ Accessible | Proper ARIA labels and roles | | 🎨 Customizable | Primary color, speech texts, expression list | | 🪶 Lightweight | Pure SVG + CSS animations, no heavy deps |

📦 Installation

npm install chatbot-assistant-ui

🚀 Quick Start

import { ChatbotAssistant } from "chatbot-assistant-ui";
import "chatbot-assistant-ui/dist/styles.css";

function App() {
  return <ChatbotAssistant welcomeMessage="Hello 👋" />;
}

🎨 Props

| Prop | Type | Default | Description | |---|---|---|---| | size | number | 220 | Width of the bot in pixels | | theme | "light" \| "dark" | "light" | Theme mode | | primaryColor | string | "#4f46e5" | Accent color (hex) | | welcomeMessage | string | "Hi there! 👋" | Text shown on hover | | speechMap | Partial<Record<Expression, string>> | — | Override speech per expression | | expressions | Expression[] | all 7 | Which expressions to cycle | | animation | boolean | true | Enable/disable idle animations | | onExpression | (expr: Expression) => void | — | Callback on expression change | | className | string | — | Additional CSS class |

🎭 Expressions

| Expression | Eyes | Mouth | Extras | |---|---|---|---| | normal | Cursor-tracking pupils | Smile | Blink animation | | hearts | ❤️ Red SVG hearts | Happy smile | Floating heart particles + blush | | surprise | ⭐ Star polygons | Open O | Star pulse animation | | laugh | Happy squint arcs | Wide open grin | Blush cheeks | | dizzy | Spinning ✕ crosses | Wavy line | Rotation animation | | cool | 😎 Sunglasses | Smirk | Lens shine | | sad | Teardrop eyes | Frown | Falling tear animation | | angry | Narrowed + brows | Teeth snarl | Red-tinted mouth |

🔧 Advanced Usage

Custom expressions + speech:

<ChatbotAssistant
  size={300}
  theme="dark"
  primaryColor="#8b5cf6"
  expressions={["hearts", "cool", "surprise"]}
  speechMap={{
    hearts: "You're amazing! 💜",
    cool: "Let's build! 🚀",
    surprise: "No way! 🤯",
  }}
  onExpression={(expr) => console.log("Expression:", expr)}
/>

Minimal (no animations):

<ChatbotAssistant animation={false} size={160} />

🏗️ Development

git clone <repo>
cd chatbot-assistant-ui
npm install
npm run build    # Build dist/
npm run dev      # Watch mode

📁 Package Structure

chatbot-assistant-ui/
├── src/
│   ├── components/
│   │   └── ChatbotAssistant.tsx    # Main component (v3 enhanced)
│   ├── hooks/
│   │   └── useMouseTracker.ts      # Cursor tracking hook
│   ├── styles/
│   │   └── chatbot.css             # Scoped CSS (cb-* prefix)
│   └── index.ts                    # Entry point
├── dist/                           # Built output
│   ├── index.js                    # CJS
│   ├── index.esm.js                # ESM
│   ├── index.d.ts                  # TypeScript declarations
│   └── styles.css                  # Minified CSS
├── package.json
├── rollup.config.mjs
├── tsconfig.json
└── README.md

🤝 Compatibility

| Framework | Works? | |---|---| | Next.js | ✅ | | Vite | ✅ | | Create React App | ✅ | | Remix | ✅ | | Gatsby | ✅ |

📄 License

MIT © Skillzy