@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

``bash
npm install @brainbase-labs/chat-widget


or

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

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

Mock Mode for Development

Test the UI without a backend connection:

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

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

Custom Mock Responses

`tsx
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:

`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

$3

For custom UI implementations:

`tsx
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 (


`tsx
embedId="your-embed-id"
position="inline"
defaultOpen={true}
/>
`

TypeScript

Full TypeScript support with exported types:

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

Development

`bash


Install dependencies

Contributing

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

License

MIT © Brainbase Labs