ChatterBox

A powerful, embeddable AI chat interface component for React that works with local Ollama models. Drop it into any React app with a single component.

Features

• 🚀 Easy to embed: Single <ChatterBox /> component
• 🖥️ Full window mode: Built-in modal overlay for expanded view
• 🎨 Fully customizable: Height, borders, colors, and more
• 🔒 Privacy-first: Works with local Ollama models
• 📱 Responsive: Works on desktop, tablet, and mobile
• 🔄 Multiple modes: Chat, Prompt, A/B Testing, and Chain workflows
• ⚡ TypeScript: Full type safety included

Quick Start

Installation

npm install @singularity-club/chatterbox
# or
yarn add @singularity-club/chatterbox

Basic Usage

import { ChatterBox } from '@singularity-club/chatterbox'

function MyApp() {
  return (
    <div>
      <h1>My Blog Post</h1>
      <p>Here's some content...</p>
      
      {/* That's it! */}
      <ChatterBox height="600px" />
    </div>
  )
}

Prerequisites

You need to have Ollama installed and running on your local machine with at least one model downloaded.

Install Ollama

# macOS/Linux
curl -fsSL https://ollama.ai/install.sh | sh

# Windows
# Download from https://ollama.ai/download

Download a model

ollama pull llama3
# or
ollama pull qwen3

Props

The ChatterBox component accepts the following props:

| Prop | Type | Default | Description | |------|------|---------|-------------| | height | string \| number | "600px" | Height of the embedded component | | width | string \| number | "100%" | Width of the embedded component | | borderRadius | string | "lg" | Border radius (Chakra UI values) | | borderWidth | string | "1px" | Border width | | borderColor | string | "border.default" | Border color (Chakra UI values) | | bg | string | "bg" | Background color (Chakra UI values) | | showBorder | boolean | true | Whether to show borders | | enableFullWindow | boolean | true | Whether to enable full window mode | | className | string | - | Custom CSS class name | | style | React.CSSProperties | - | Custom inline styles | | autoInitialize | boolean | true | Whether to auto-initialize the app |

Examples

Basic Embed

<ChatterBox />

Custom Styling

<ChatterBox 
  height="500px"
  borderRadius="xl"
  borderColor="blue.300"
  bg="blue.50"
/>

Without Full Window Mode

<ChatterBox 
  enableFullWindow={false}
  height="400px"
/>

Multiple Instances

<div>
  <h2>Chat with GPT-4</h2>
  <ChatterBox height="500px" />
  
  <h2>Chat with Llama</h2>
  <ChatterBox height="500px" />
</div>

Custom CSS

<ChatterBox 
  className="my-custom-chatterbox"
  style={{ boxShadow: '0 10px 30px rgba(0,0,0,0.1)' }}
/>

AI Modes

ChatterBox supports multiple AI interaction modes:

• Chat: Traditional conversation interface
• Prompt: Single prompt/response mode
• A/B Test: Compare multiple prompts side by side
• Chain: Multi-step workflows with templating

Chakra UI Integration

This component is built with Chakra UI. Make sure your app is wrapped with a Chakra UI provider:

import { ChakraProvider, defaultSystem } from '@chakra-ui/react'
import { ChatterBox } from '@singularity-club/chatterbox'

function App() {
  return (
    <ChakraProvider value={defaultSystem}>
      <ChatterBox />
    </ChakraProvider>
  )
}

Development

Local Development

git clone <repo-url>
cd chatterbox
npm install
npm run dev

Building

npm run build

Testing

npm test

License

MIT License - see LICENSE file for details.

Built with ❤️ by singularity-club