@verbox/react

Official Verbox AI Chat Widget for React & Next.js.

A fully-featured, production-ready embeddable chat widget with typing animation, image upload, feedback, theming, and more.

Installation

npm install @verbox/react
# or
yarn add @verbox/react
# or
pnpm add @verbox/react

Quick Start

import { VerboxWidget } from "@verbox/react";

function App() {
  return <VerboxWidget botId="your-bot-id" />;
}

That's it. The widget connects to https://api.verbox.app by default. No API key needed.

Features

• Typing Animation - Word-by-word text reveal with blinking cursor (like ChatGPT)
• Image Upload - Click to attach images (up to 5 per message)
• Feedback - Thumbs up/down on bot responses
• Dark/Light Themes - Built-in themes with full customization
• Chat History - Persistent sessions via localStorage
• Suggested Questions - Configurable chips and follow-up suggestions
• Markdown - Bold, italic, code blocks, links rendered in messages
• Responsive - Full-screen on mobile, floating window on desktop
• Headless Mode - Use hooks directly for fully custom UIs

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | botId | string | required | Your Verbox bot ID | | baseUrl | string | "https://api.verbox.app" | Verbox API URL (rarely needed) | | theme | "light" \| "dark" | "light" | Color theme | | primaryColor | string | "#685AFF" | Accent color | | position | string | "bottom-right" | Widget position | | headerTitle | string | "Verbox" | Header title | | welcomeMessage | string | "Hi! How can I help you today?" | Welcome message | | inputPlaceholder | string | "Type your message..." | Input placeholder | | avatarUrl | string | - | Custom bot avatar URL | | borderRadius | number | 16 | Window border radius | | showBranding | boolean | true | Show "Powered by Verbox" | | enableImageUpload | boolean | true | Enable image attachments | | enableFeedback | boolean | true | Enable feedback buttons | | enableHistory | boolean | true | Enable session persistence | | suggestedQuestions | string[] | [] | Initial suggested questions | | typingAnimation | boolean | true | Enable typing animation | | typingSpeed | number | 30 | Typing animation speed (ms per word) | | zIndex | number | 9999 | z-index for widget elements |

Event Callbacks

<VerboxWidget
  botId="your-bot-id"
  onOpen={() => console.log("Widget opened")}
  onClose={() => console.log("Widget closed")}
  onMessageSent={(msg) => console.log("User sent:", msg)}
  onMessageReceived={(msg) => console.log("Bot replied:", msg)}
  onError={(err) => console.error("Error:", err)}
/>

Headless Mode (Custom UI)

Use the VerboxProvider and useVerbox hook to build a completely custom chat interface:

import { VerboxProvider, useVerbox } from "@verbox/react";

function CustomChat() {
  const {
    messages,
    isLoading,
    suggestedFollowUps,
    sendMessage,
    submitFeedback,
    clearHistory,
  } = useVerbox();

  return (
    <div>
      {messages.map((msg) => (
        <div key={msg.id}>
          <strong>{msg.role}:</strong> {msg.content}
        </div>
      ))}
      {isLoading && <div>Typing...</div>}
    </div>
  );
}

function App() {
  return (
    <VerboxProvider botId="your-bot-id">
      <CustomChat />
    </VerboxProvider>
  );
}

Using Individual Hooks

useVerboxChat

Low-level hook for chat state management:

import { useVerboxChat } from "@verbox/react";

function MyChat() {
  const chat = useVerboxChat({
    botId: "your-bot-id",
  });

  return (
    <div>
      <div>{chat.messages.map(/* render */)}</div>
      <button onClick={() => chat.sendMessage("Hello!")}>Send</button>
    </div>
  );
}

useTypingAnimation

Standalone typing animation hook for any text:

import { useTypingAnimation } from "@verbox/react";

function TypedText() {
  const { displayedText, isAnimating, animate } = useTypingAnimation({
    speed: 30,
    enabled: true,
  });

  return (
    <div>
      <p>{displayedText}{isAnimating && <span className="cursor">|</span>}</p>
      <button onClick={() => animate("Hello, this text will type out word by word!")}>
        Start
      </button>
    </div>
  );
}

Next.js Usage

Since the widget uses browser APIs, wrap it with dynamic import in Next.js:

import dynamic from "next/dynamic";

const VerboxWidget = dynamic(
  () => import("@verbox/react").then((mod) => mod.VerboxWidget),
  { ssr: false }
);

export default function Layout({ children }) {
  return (
    <>
      {children}
      <VerboxWidget botId="your-bot-id" theme="dark" />
    </>
  );
}

Or use the "use client" directive:

"use client";
import { VerboxWidget } from "@verbox/react";

export function ChatWidget() {
  return <VerboxWidget botId="your-bot-id" />;
}

License

MIT