\n \n {messages.map(msg => (\n \n
\n )\n}\n```\n\n---\n\n## Custom Components\n\nThe library supports **custom component overrides**, allowing you to replace default message rendering components with your own implementations while maintaining full type safety and integration with the rest of the UI.\n\n### Why Use Custom Components?\n\n- π¨ **Branding** - Match your company's design system\n- β¨ **Enhanced Features** - Add custom interactions like click-to-copy or inline editing\n- π **Different Layouts** - Customize message bubble styles and positioning\n- βΏ **Accessibility** - Add enhanced keyboard navigation or screen reader support\n- π **Integration** - Connect messages to your existing component library\n\n### Available Component Overrides\n\nYou can override any of these message rendering components:\n\n- `AssistantMessage` - Assistant text messages\n- `ToolCallMessage` - Tool invocation messages\n- `ToolResultMessage` - Tool execution results\n- `SystemMessage` - System-level messages\n- `StreamingMessage` - Streaming events\n\n### Basic Usage\n\n```tsx\nimport { FullChatApp, type CustomComponents } from '@10play/claude-agent-sdk-ui'\n\n// Define your custom components\nconst customComponents: CustomComponents = {\n AssistantMessage: MyCustomAssistantMessage,\n ToolCallMessage: MyCustomToolCallMessage,\n // ... other components\n}\n\nfunction App() {\n return (\n \n
\n )\n}\n```\n\n### Component Props Types\n\nThe library exports all component prop types for type safety:\n\n```tsx\nimport type {\n CustomAssistantMessageProps,\n CustomToolCallMessageProps,\n CustomToolResultMessageProps,\n CustomSystemMessageProps,\n CustomStreamingMessageProps\n} from '@10play/claude-agent-sdk-ui'\n```\n\n### Using with ChatInterface\n\nCustom components work at all levels of the API:\n\n```tsx\nimport { ChatInterface, type CustomComponents } from '@10play/claude-agent-sdk-ui'\n\nconst customComponents: CustomComponents = {\n AssistantMessage: MyCustomAssistantMessage,\n}\n\nfunction MyChat() {\n return (\n \n π€ AI Assistant\n
\n \n
\n )\n}\n```\n\n### Reusing Default Components\n\nYou can import and reuse the default components in your custom implementations:\n\n```tsx\nimport {\n AssistantMessage,\n ToolCallMessage,\n MarkdownEditor,\n CollapsibleCodeBlock\n} from '@10play/claude-agent-sdk-ui'\n\n// Wrap the default component with additional features\nexport function EnhancedAssistantMessage(props) {\n return (\n \n {toolName}\n {toolResult.is_error && (\n Error\n )}\n \n {new Date(timestamp).toLocaleTimeString()}\n \n
\n\n \n \n
\n )\n}\n```\n\n### Notes\n\n- All component overrides are **optional** - only override what you need\n- Custom components receive the **same props** as the default components\n- The library handles all message routing and state management\n- You can use any React components, hooks, and patterns in your custom components\n\n---\n\n## API Reference\n\n### Main Components\n\n#### `\n
\n```\n\n```css\n/* Override specific component styles */\n.my-chat-wrapper {\n /* Message bubbles */\n --muted: 210 40% 98%;\n\n /* Adjust spacing */\n --spacing-message: 1rem;\n}\n\n/* Target internal components (use with caution) */\n.my-chat-wrapper .message-bubble {\n @apply shadow-lg;\n}\n```\n\n### Dark Mode Customization\n\nThe library automatically applies dark mode classes. You can customize dark mode separately:\n\n```css\n.dark {\n /* Override dark mode colors */\n --background: 220 15% 8%; /* Custom dark background */\n --card: 220 15% 12%; /* Slightly lighter cards */\n --border: 220 15% 20%; /* Visible borders in dark mode */\n}\n```\n\n### Markdown Styling\n\nCustomize markdown rendering in messages:\n\n```css\n/* Override markdown styles */\n.markdown-editor {\n /* Code blocks */\n pre {\n @apply bg-muted rounded-lg p-4;\n }\n\n /* Inline code */\n code {\n @apply bg-accent text-accent-foreground px-1 rounded;\n }\n\n /* Headings */\n h1, h2, h3 {\n @apply font-bold text-foreground;\n }\n\n /* Links */\n a {\n @apply text-primary hover:underline;\n }\n}\n```\n\n---\n\n## Backend API Specification\n\nThe UI library expects your backend to implement the following REST API endpoints and WebSocket protocol.\n\n### REST API Endpoints\n\n#### Sessions Management\n\n**GET `/api/sessions`**\n- **Description:** List all sessions\n- **Response:**\n```typescript\n{\n sessions: Array<{\n id: string\n title: string\n created_at: string\n updated_at: string\n metadata?: {\n working_directory?: string\n model?: string\n [key: string]: any\n }\n }>\n}\n```\n\n**POST `/api/sessions`**\n- **Description:** Create a new session\n- **Request Body:**\n```typescript\n{\n title?: string\n metadata?: {\n working_directory?: string\n model?: string\n [key: string]: any\n }\n}\n```\n- **Response:**\n```typescript\n{\n session: {\n id: string\n title: string\n created_at: string\n updated_at: string\n metadata?: object\n }\n}\n```\n\n**GET `/api/sessions/:id`**\n- **Description:** Get a specific session with messages\n- **Response:**\n```typescript\n{\n session: {\n id: string\n title: string\n created_at: string\n updated_at: string\n metadata?: object\n },\n messages: Array<{\n id: string\n session_id: string\n sdk_message: SDKMessage // From @anthropic-ai/claude-agent-sdk\n timestamp: string\n }>\n}\n```\n\n**PUT `/api/sessions/:id`**\n- **Description:** Update session (title, metadata)\n- **Request Body:**\n```typescript\n{\n title?: string\n metadata?: object\n}\n```\n- **Response:**\n```typescript\n{\n session: {\n id: string\n title: string\n updated_at: string\n metadata?: object\n }\n}\n```\n\n**DELETE `/api/sessions/:id`**\n- **Description:** Delete a session\n- **Response:**\n```typescript\n{\n success: boolean\n}\n```\n\n**POST `/api/sessions/:id/messages`**\n- **Description:** Load messages into a session (for import)\n- **Request Body:**\n```typescript\n{\n title?: string\n messages: Array\n \n {virtualizer.getVirtualItems().map((virtualRow) => {\n const message = messages[virtualRow.index]\n return (\n \n
\n )\n })}\n \n \n )\n}\n```\n\n### Pagination\n\nImplement message pagination for large sessions:\n\n```tsx\nfunction PaginatedChat({ session }) {\n const [page, setPage] = useState(0)\n const [pageSize] = useState(50)\n\n const { messages } = useChatSession({ session, websocketUrl })\n\n // Show only recent messages\n const visibleMessages = messages.slice(-pageSize * (page + 1))\n\n return (\n \n {messages.length > pageSize && (\n \n )}\n
\n )\n}\n```\n\n### Debounced Updates\n\nDebounce expensive operations like title updates:\n\n```tsx\nimport { useDebouncedCallback } from 'use-debounce'\n\nfunction DebouncedTitleEdit() {\n const debouncedUpdate = useDebouncedCallback(\n (newTitle: string) => {\n updateTitle(newTitle)\n },\n 1000 // Wait 1 second after user stops typing\n )\n\n return (\n {/* Display stats */}
\n}\n```\n\n### Image Optimization\n\nOptimize image attachments before sending:\n\n```tsx\nasync function optimizeImage(file: File): Promise\n My Custom Chat \n
\n \n \n \n\n
\n )\n}\n```\n\n### 6. Handling Tool Results\n\n```tsx\nimport { useToolResultContext } from '@10play/claude-agent-sdk-ui'\n\nfunction ToolResultsPanel() {\n const { toolResults, clearToolResults } = useToolResultContext()\n\n return (\n Chat
\n\n {messages.map((msg, idx) => (\n
\n\n \n
\n )\n}\n```\n\n### 7. Custom Message Handling\n\n```tsx\nimport { useChatSession } from '@10play/claude-agent-sdk-ui'\n\nfunction ChatWithLogging({ session }) {\n const { sendMessage, messages } = useChatSession({\n session,\n websocketUrl: 'ws://localhost:4001/ws',\n onMessagesChange: (msgs) => {\n // Custom logging or analytics\n console.log('Messages updated:', msgs.length)\n analytics.track('messages_changed', { count: msgs.length })\n }\n })\n\n const handleSend = async (text: string) => {\n // Pre-process message\n const processed = text.trim().toLowerCase()\n\n // Send to chat\n await sendMessage(processed)\n\n // Post-process\n console.log('Message sent:', processed)\n }\n\n return Tool Results ({toolResults.length})
\n \n {toolResults.map((result, idx) => (\n\n {result.name}: {result.status}\n
\n ))}\n