@brainbase-labs/chat-widget

A React chat widget for embedding Brainbase Labs AI agents in your applications.

Features

• 🚀 Drop-in React component - Add AI chat to your app in minutes
• 🎨 Fully customizable - Theme with CSS variables or override styles
• 📱 Responsive - Works on desktop and mobile
• 🔄 Session persistence - Conversations survive page refreshes
• 🛠️ Tool call support - Display function calls and results
• 🧪 Mock mode - Develop UI without a backend connection

Installation

npm install @brainbase-labs/chat-widget
# or
yarn add @brainbase-labs/chat-widget
# or
pnpm add @brainbase-labs/chat-widget

Quick Start

import { ChatWidget } from '@brainbase-labs/chat-widget';
import '@brainbase-labs/chat-widget/styles.css';

function App() {
  return (
    <ChatWidget
      embedId="your-embed-id-here"
      onSessionEnd={(session) => console.log('Session ended:', session)}
    />
  );
}

Mock Mode for Development

Test the UI without a backend connection:

import { ChatWidget } from '@brainbase-labs/chat-widget';
import '@brainbase-labs/chat-widget/styles.css';

function App() {
  return (
    <ChatWidget
      embedId="demo"
      mockMode={true}
      defaultOpen={true}
      agentName="Dev Assistant"
    />
  );
}

Custom Mock Responses

<ChatWidget
  embedId="demo"
  mockMode={true}
  mockResponses={[
    {
      trigger: /order|status/i,
      response: "Let me look up your order...",
      toolCalls: [
        {
          name: 'lookup_order',
          arguments: { orderId: '12345' },
          result: { status: 'shipped' }
        }
      ]
    },
    {
      trigger: /.*/,
      response: "I'm here to help! Ask me anything.",
      delay: 500
    }
  ]}
/>

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | embedId | string | Required | The embed ID from your Brainbase Labs deployment | | apiBaseUrl | string | Production URL | API base URL for the Brainbase Labs API | | mockMode | boolean | false | Enable mock mode for UI development | | mockResponses | MockResponse[] | Default responses | Custom mock responses | | position | 'bottom-right' \| 'bottom-left' \| 'inline' | 'bottom-right' | Widget position | | defaultOpen | boolean | false | Whether widget starts open | | primaryColor | string | '#1a1a2e' | Primary theme color (hex) | | agentName | string | From deployment | Agent display name | | className | string | - | Custom CSS class | | onSessionStart | (sessionId: string) => void | - | Session start callback | | onSessionEnd | (session: Session) => void | - | Session end callback | | onMessage | (message: Message) => void | - | Message callback | | onError | (error: Error) => void | - | Error callback |

Theming

The widget uses CSS custom properties for theming. Override them in your CSS:

:root {
  /* Primary brand color */
  --bb-primary-color: #1a1a2e;
  
  /* Accent color for highlights */
  --bb-accent-color: #6366f1;
  
  /* Background colors */
  --bb-surface-bg: #ffffff;
  --bb-surface-secondary: #f8f9fb;
  
  /* Text colors */
  --bb-text-primary: #1a1a2e;
  --bb-text-secondary: #6b7280;
  
  /* Message bubbles */
  --bb-user-message-bg: var(--bb-primary-color);
  --bb-user-message-text: #ffffff;
  --bb-assistant-message-bg: var(--bb-surface-secondary);
  --bb-assistant-message-text: var(--bb-text-primary);
  
  /* Widget dimensions */
  --bb-widget-width: 400px;
  --bb-widget-height: 600px;
}

Advanced Usage

Using the Chat Hook

For custom UI implementations:

import { useChat, createMockAPIClient } from '@brainbase-labs/chat-widget';

function CustomChat() {
  const mockClient = createMockAPIClient();
  
  const chat = useChat({
    config: {
      embedId: 'demo',
      deploymentId: 'mock',
      workerId: 'mock',
      flowId: 'mock',
    },
    apiClient: mockClient,
    mockMode: true,
  });

  return (
    <div>
      {chat.messages.map(msg => (
        <div key={msg.id}>{msg.content}</div>
      ))}
      <input
        onKeyDown={(e) => {
          if (e.key === 'Enter') {
            chat.sendMessage(e.currentTarget.value);
            e.currentTarget.value = '';
          }
        }}
      />
    </div>
  );
}

Inline Mode

Embed the chat directly in your page layout instead of as a floating widget:

<ChatWidget
  embedId="your-embed-id"
  position="inline"
  defaultOpen={true}
/>

TypeScript

Full TypeScript support with exported types:

import type {
  ChatWidgetProps,
  Message,
  Session,
  ToolCall,
  DeploymentConfig,
} from '@brainbase-labs/chat-widget';

Development

# Install dependencies
npm install

# Run Storybook for development
npm run storybook

# Build the library
npm run build

# Type check
npm run typecheck

# Lint
npm run lint

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting a PR.

License

MIT © Brainbase Labs