bettercx-widget

# BetterCX Widget - React Integration > Production-ready React wrapper for the BetterCX chat widget. Zero configuration, plug-and-play integration. The BetterCX Widget React component provides seamless integration of AI-powered customer support into your React applications. Built with TypeScript and optimized for performance, it offers a complete solution for modern web applications. ## 🚀 Quick Start ### Installation ```bash npm install bettercx-widget ``` ### Basic Usage ```tsx import React from 'react'; import { BetterCXWidgetReact } from 'bettercx-widget/react'; function App() { return <BetterCXWidgetReact publicKey="pk_your_widget_key_here" theme="auto" />; } ``` **That's it!** The widget will automatically initialize and appear in the bottom-right corner. ## 📦 Import Options ```tsx // Named import (recommended) import { BetterCXWidgetReact } from 'bettercx-widget/react'; // With TypeScript types import { BetterCXWidgetReact, BetterCXWidgetReactRef, BetterCXWidgetReactProps } from 'bettercx-widget/react'; ``` ## 🎯 Props Reference | Prop | Type | Default | Required | Description | | --------------- | ----------------------------- | --------- | -------- | ---------------------------------------------- | | `publicKey` | `string` | - | ✅ | Your widget public key from BetterCX dashboard | | `theme` | `'light' \| 'dark' \| 'auto'` | `'auto'` | ❌ | Widget theme preference | | `position` | `'left' \| 'right'` | `'right'` | ❌ | Widget position on screen | | `onWidgetEvent` | `function` | - | ❌ | Event handler for widget interactions | | `className` | `string` | - | ❌ | Custom CSS class name | | `style` | `object` | - | ❌ | Inline styles object | ## 🎮 Programmatic Control Use refs to control the widget programmatically: ```tsx import React, { useRef } from 'react'; import { BetterCXWidgetReact, BetterCXWidgetReactRef } from 'bettercx-widget/react'; function App() { const widgetRef = useRef<BetterCXWidgetReactRef>(null); const handleOpenChat = () => { widgetRef.current?.open(); }; const handleSendMessage = () => { widgetRef.current?.sendMessage('Hello from React!'); }; return ( <div> <button onClick={handleOpenChat}>Open Chat</button> <button onClick={handleSendMessage}>Send Message</button> <BetterCXWidgetReact ref={widgetRef} publicKey="pk_your_widget_key_here" onWidgetEvent={event => console.log('Widget event:', event)} /> </div> ); } ``` ### Available Methods ```tsx const widgetRef = useRef<BetterCXWidgetReactRef>(null); // Open the chat widget await widgetRef.current?.open(); // Close the chat widget await widgetRef.current?.close(); // Toggle the chat widget await widgetRef.current?.toggle(); // Send a message programmatically await widgetRef.current?.sendMessage('Hello!'); ``` ## 📡 Event Handling Track widget interactions for analytics and custom logic: ```tsx import { useState } from 'react'; function App() { const [events, setEvents] = useState([]); const handleWidgetEvent = event => { setEvents(prev => [...prev, event]); console.log('Widget Event:', event); // Track analytics if (event.type === 'opened') { analytics.track('chat_opened'); } }; return <BetterCXWidgetReact publicKey="pk_your_widget_key_here" onWidgetEvent={handleWidgetEvent} />; } ``` ### Event Types - `opened` - Widget was opened by user - `closed` - Widget was closed by user - `message-sent` - User sent a message - `message-received` - AI responded with a message - `error` - An error occurred - `session-created` - Authentication session created ## 🎨 Styling & Customization ### Custom CSS Classes ```tsx <BetterCXWidgetReact publicKey="pk_your_widget_key_here" className="my-custom-widget" /> ``` ### Inline Styles ```tsx <BetterCXWidgetReact publicKey="pk_your_widget_key_here" style={{ zIndex: 9999 }} /> ``` ### CSS Custom Properties Override widget colors to match your brand: ```css bettercx-widget { --bcx-primary: #your-brand-color; --bcx-background: #ffffff; --bcx-text: #333333; --bcx-border: #e0e0e0; } ``` ### CSS-in-JS ```tsx const widgetStyle = { 'zIndex': 9999, '--bcx-primary': '#ff6b6b', '--bcx-background': '#ffffff', }; <BetterCXWidgetReact publicKey="pk_your_widget_key_here" style={widgetStyle} />; ``` ## 🌙 Theme Configuration ### Automatic Theme Detection ```tsx // Automatically detects website theme (recommended) <BetterCXWidgetReact theme="auto" /> ``` ### Manual Theme Selection ```tsx // Light theme <BetterCXWidgetReact theme="light" /> // Dark theme <BetterCXWidgetReact theme="dark" /> ``` ## 🔧 Advanced Configuration ### Complete Example ```tsx <BetterCXWidgetReact publicKey="pk_your_widget_key_here" theme="dark" position="left" className="custom-widget" style={{ zIndex: 9999 }} onWidgetEvent={event => { // Handle different event types switch (event.type) { case 'opened': console.log('Chat opened'); break; case 'message-sent': console.log('Message sent:', event.data); break; case 'error': console.error('Widget error:', event.data); break; } }} /> ``` ## 📱 Responsive Behavior The widget automatically adapts to different screen sizes: - **Desktop** (≥1024px): Floating widget in corner - **Tablet** (768px-1023px): Optimized for touch interaction - **Mobile** (<768px): Full-screen chat experience ## 🚫 Error Handling The widget gracefully handles errors without showing error UI to users: - **Invalid public key**: Widget remains hidden - **Network issues**: Widget remains hidden - **Configuration errors**: Widget remains hidden ## 🔍 TypeScript Support Full TypeScript support with comprehensive type definitions: ```tsx import { BetterCXWidgetReact, BetterCXWidgetReactRef, BetterCXWidgetReactProps } from 'bettercx-widget/react'; // Component props are fully typed const props: BetterCXWidgetReactProps = { publicKey: 'pk_your_key', theme: 'auto', onWidgetEvent: event => console.log(event), }; // Ref methods are fully typed const widgetRef = useRef<BetterCXWidgetReactRef>(null); ``` ## 🎯 Production Checklist - ✅ **Minimal configuration** - Only `publicKey` required - ✅ **Auto-initialization** - Works immediately on load - ✅ **Error handling** - Graceful failure without UI - ✅ **TypeScript support** - Full type safety - ✅ **Responsive design** - Works on all devices - ✅ **Event system** - Track user interactions - ✅ **Programmatic control** - Open/close/send messages - ✅ **Theme support** - Light, dark, and auto themes - ✅ **Zero dependencies** - No additional packages required ## 🚀 Deployment 1. **Install the package**: ```bash npm install bettercx-widget ``` 2. **Add to your app**: ```tsx import { BetterCXWidgetReact } from 'bettercx-widget/react'; ``` 3. **Configure with your public key**: ```tsx <BetterCXWidgetReact publicKey="pk_your_key_here" /> ``` 4. **Deploy** - The widget is ready for production! ## 🛠️ Troubleshooting ### Common Issues **Widget not appearing:** - Verify your public key is correct - Check browser console for errors - Ensure your domain is authorized in BetterCX dashboard **Styling conflicts:** - Check for CSS conflicts with your existing styles - Verify custom properties are set correctly - Test with different themes **TypeScript errors:** - Ensure you're importing the correct types - Check that your React version is compatible (≥16.8.0) ## 📚 Examples Check out our comprehensive examples: - [Interactive Demo](./examples/react-example/) - Complete React application - [Landing Page](./examples/landing-page-example/) - Professional landing page - [E-commerce Store](./examples/ecommerce-example/) - Online store integration ## 🤝 Support - **Documentation**: [Full API Reference](./readme.md) - **Examples**: [Integration Examples](./examples/) - **Support**: [BetterCX Support Portal](https://support.bettercx.ai) - **Email**: support@bettercx.ai --- **Ready to enhance your customer support?** The React wrapper is production-ready with minimal configuration and maximum reliability! 🚀