--- name: chatkit-client-widget-creator description: This skill helps create React chat widgets using the ChatKit React library, following best practices for floating chat interfaces with thread persistence and proper configuration. --- # ChatKit Client Widget Creator This skill helps create React chat widgets using the ChatKit React library, following best practices for floating chat interfaces with thread persistence and proper configuration. ## Usage Instructions When a user needs to create a ChatKit client widget, use this skill to generate: 1. React component with proper state management 2. useChatKit hook configuration with API settings 3. Thread persistence using localStorage 4. Floating chat button with open\/close functionality 5. Styling and UI components with proper accessibility 6. Error handling and lifecycle management ## How the Client Connects The client connects to the backend in this way: 1. **API Configuration**: Points to the backend ChatKit endpoint (`http:\/\/localhost:8000\/chatkit`) 2. **Thread Management**: Uses localStorage to persist thread IDs across sessions 3. **Event Handling**: Responds to thread changes, errors, and ready states 4. **UI Integration**: Renders the ChatKit component with the control object ## Best Practices to Follow - Use localStorage for thread persistence across page reloads - Implement proper loading states with `isReady` flag - Handle thread ID changes by saving to localStorage - Include proper error handling callbacks - Use floating UI pattern with open\/close states - Implement "New Chat" functionality that clears thread ID - Include accessibility attributes (aria-label) - Use proper CSS class utilities (cn) for conditional styling - Configure theme options to match brand colors - Add appropriate event callbacks for debugging and monitoring ## Template Structure ### Complete ChatKit Widget Template: ```tsx import { ChatKit, useChatKit } from '@openai\/chatkit-react' import { useState, useEffect, Activity } from 'react' import { MessageCircle, X, RefreshCw } from 'lucide-react' import { cn } from '@site\/src\/lib\/utils' \/\/ Adjust import path as needed export const ChatWidget = () => { const [initialThread, setInitialThread] = useState(null) const [isReady, setIsReady] = useState(false) const [isChatOpen, setIsChatOpen] = useState(false) \/\/ Load saved thread ID on mount useEffect(() => { const savedThread = localStorage.getItem('chatkit-thread-id') setInitialThread(savedThread) }, []) const { control } = useChatKit({ api: { url: 'http:\/\/localhost:8000\/chatkit', \/\/ Update to your backend URL domainKey: 'localhost', \/\/ Update domain as needed }, initialThread: initialThread, theme: { colorScheme: 'dark', \/\/ or 'light' color: { accent: { primary: 'hsl(174, 72%, 56%)', level: 1 }, \/\/ Adjust colors as needed }, radius: 'round', \/\/ or 'sharp' or 'smooth' }, startScreen: { greeting: 'Welcome to Your Assistant!', prompts: [ { label: 'Hello', prompt: 'Say hello and introduce yourself' }, { label: 'Help', prompt: 'What can you help me with?' }, \/\/ Add more starter prompts as needed ], }, composer: { placeholder: 'Ask me anything...', \/\/ Customize placeholder text }, onThreadChange: ({ threadId }) => { console.log('Thread changed:', threadId) if (threadId) { localStorage.setItem('chatkit-thread-id', threadId) } }, onError: ({ error }) => { console.error('ChatKit error:', error) }, onReady: () => { console.log('ChatKit is ready!') }, }) return (<> {\/* Floating Chat Button (bottom-right) *\/} {!isChatOpen && (