@copilotz/chat-ui

The chat interface your AI agent deserves.

Chat UI libraries give you message bubbles. Your AI agent has tool calls, streaming responses, file uploads, audio recording, persistent threads, and user memories. This gives you everything else.


---

The Problem

You're building a frontend for your AI agent. You grab a chat UI library. It renders messages. Great.

Then you need to show tool calls — the library doesn't support that. Streaming with a thinking indicator — you'll build it yourself. File uploads with previews — more custom code. Audio recording — even more. Thread management with search and archive — at this point you're maintaining your own chat UI.

There's no shadcn for agentic chat. Just parts.

The Solution

@copilotz/chat-ui is the complete chat interface for AI agents. Everything you need to ship a production chat experience, in one package:

| What You Need | What This Gives You |
|---------------|---------------------|
| Messages | Markdown with syntax highlighting, streaming with thinking indicator |
| Tool Calls | Expandable cards with args, results, status, and execution time |
| Media | Image/audio/video attachments with native playback controls |
| Input | File upload (drag & drop), audio recording, attachment previews |
| Threads | Sidebar with search, archive, date grouping, rename, delete |
| User Profile | Dynamic fields, memories (CRUD), agent vs user distinction |
| Customization | 50+ labels (i18n-ready), feature toggles, 4 presets, theming |

One package. Backend-agnostic. Production-ready.

---

Quick Start

``bash
npm install @copilotz/chat-ui
`

Import the styles once in your app:

`tsx
import '@copilotz/chat-ui/styles.css';
`

Drop in the component:

`tsx
import { ChatUI } from '@copilotz/chat-ui';

function App() {
const [messages, setMessages] = useState([]);

return (
messages={messages}
user={{ id: 'user-1', name: 'Alex' }}
assistant={{ name: 'Assistant' }}
callbacks={{
onSendMessage: (content, attachments) => {
// Handle message — connect to your backend
},
}}
/>
);
}
`

That's it. You have a full-featured chat interface.

---

Features

$3

Real-time streaming with a thinking indicator while waiting for the first token. Markdown rendering with syntax highlighting. Tool calls displayed as expandable cards showing name, arguments, result, and execution time.

`tsx
const message = {
id: '1',
role: 'assistant',
content: 'Here is the chart you requested.',
timestamp: Date.now(),
isStreaming: false,
toolCalls: [{
id: 'tc-1',
name: 'generate_chart',
arguments: { type: 'bar', data: [1, 2, 3] },
result: { url: 'https://...' },
status: 'completed',
startTime: 1234567890,
endTime: 1234567891,
}],
attachments: [{
kind: 'image',
dataUrl: 'data:image/png;base64,...',
mimeType: 'image/png',
}],
};
`

$3

File uploads with drag & drop. Audio recording with built-in MediaRecorder. Attachment previews with playback controls. Upload progress indicators. Stop generation button during streaming.

$3

Sidebar with threads grouped by date (Today, Yesterday, etc.). Search and filter. Archive toggle. Create, rename, and delete with confirmation dialogs. Collapsible icon mode for more screen space.

$3

Built-in sheet panel with user info, dynamic custom fields (auto-detects icons based on field names), and a memories section. Memories support CRUD operations and distinguish between agent-created and user-created entries.

$3

ChatGPT-style dropdown for switching between multiple agents. Displays agent avatars, names, and descriptions (truncated for long text). Consecutive messages from the same sender are automatically grouped to save screen space.

`tsx
const agents = [
{ id: 'assistant', name: 'Assistant', description: 'General purpose helper' },
{ id: 'coder', name: 'Code Expert', description: 'Specialized in programming', avatarUrl: '/coder.png' },
];

agentOptions={agents}
selectedAgentId="assistant"
onSelectAgent={(agentId) => setSelectedAgent(agentId)}
// ... other props
/>
`

---

Configuration

The configuration system lets you customize everything without touching the component internals.

$3

Start with a preset and override what you need:

`tsx
import { ChatUI, chatConfigPresets } from '@copilotz/chat-ui';

// Minimal: no threads, no file upload, compact mode


// Full: all features enabled, timestamps, word count


// Developer: tool calls visible, timestamps, file upload


// Customer Support: threads, file upload, no message editing

`

$3

`tsx
config={{
branding: {
title: 'Acme Assistant',
subtitle: 'How can I help you today?',
logo: ,
avatar: ,
},
labels: {
inputPlaceholder: 'Ask me anything...',
sendButton: 'Send',
newChat: 'New Conversation',
thinking: 'Thinking...',
toolUsed: 'Tool Used',
// ... 50+ customizable labels for full i18n
},
features: {
enableThreads: true,
enableFileUpload: true,
enableAudioRecording: true,
enableMessageEditing: true,
enableMessageCopy: true,
enableRegeneration: true,
enableToolCallsDisplay: true,
maxAttachments: 4,
maxFileSize: 10 1024 1024, // 10MB
},
ui: {
theme: 'auto', // 'light' | 'dark' | 'auto'
showTimestamps: true,
showAvatars: true,
compactMode: false,
},
}}
/>
`

$3

Add a custom component to the right sidebar (e.g., profile info, settings, context):

`tsx
config={{
customComponent: {
label: 'Profile',
icon: ,
component: ({ onClose, isMobile }) => (



),
},
}}
/>
`

---

Callbacks

All user interactions are handled through callbacks. This keeps the component purely presentational — you control the data.

`tsx
callbacks={{
// Messages
onSendMessage: (content, attachments, stateCallback) => {},
onEditMessage: (messageId, newContent, stateCallback) => {},
onDeleteMessage: (messageId, stateCallback) => {},
onRegenerateMessage: (messageId, stateCallback) => {},
onCopyMessage: (messageId, content, stateCallback) => {},
onStopGeneration: (stateCallback) => {},

// Threads
onCreateThread: (title, stateCallback) => {},
onSelectThread: (threadId, stateCallback) => {},
onRenameThread: (threadId, newTitle, stateCallback) => {},
onDeleteThread: (threadId, stateCallback) => {},
onArchiveThread: (threadId, stateCallback) => {},

// User Menu
onViewProfile: () => {},
onOpenSettings: () => {},
onThemeChange: (theme) => {}, // 'light' | 'dark' | 'system'
onLogout: () => {},
}}
/>
`

---

Props Reference

$3

| Prop | Type | Description |
|------|------|-------------|
| messages | ChatMessage[] | Array of messages to display |
| threads | ChatThread[] | Array of conversation threads |
| currentThreadId | string \| null | Currently selected thread ID |
| config | ChatConfig | Configuration object |
| callbacks | ChatCallbacks | Event handlers |
| isGenerating | boolean | Whether the assistant is generating a response |
| user | { id, name?, avatar?, email? } | Current user info |
| assistant | { name?, avatar?, description? } | Assistant info |
| suggestions | string[] | Suggested prompts shown when no messages |
| agentOptions | AgentOption[] | Available agents for the selector dropdown |
| selectedAgentId | string \| null | Currently selected agent ID |
| onSelectAgent | (agentId: string) => void | Called when user selects an agent |
| initialInput | string | Pre-fill the input field (e.g., from URL params) |
| onInitialInputConsumed | () => void | Called when initial input is modified/sent |
| className | string | Additional CSS classes |

$3

`typescript
interface ChatMessage {
id: string;
role: 'user' | 'assistant' | 'system';
content: string;
timestamp: number;
attachments?: MediaAttachment[];
isStreaming?: boolean;
isComplete?: boolean;
isEdited?: boolean;
toolCalls?: ToolCall[];
metadata?: Record;
}
`

$3

`typescript
type MediaAttachment =
| { kind: 'image'; dataUrl: string; mimeType: string; fileName?: string }
| { kind: 'audio'; dataUrl: string; mimeType: string; durationMs?: number }
| { kind: 'video'; dataUrl: string; mimeType: string; poster?: string };
`

$3

`typescript
interface ToolCall {
id: string;
name: string;
arguments: Record;
result?: any;
status: 'pending' | 'running' | 'completed' | 'failed';
startTime?: number;
endTime?: number;
}
`

$3

`typescript
interface AgentOption {
id: string;
name: string;
description?: string; // Shown in dropdown (truncated to 2 lines)
avatarUrl?: string; // Agent avatar image
}
`

---

Exports

`tsx
// Components
export { ChatUI } from './components/chat/ChatUI';
export { ChatHeader } from './components/chat/ChatHeader';
export { ChatInput } from './components/chat/ChatInput';
export { Message } from './components/chat/Message';
export { Sidebar } from './components/chat/Sidebar';
export { ThreadManager } from './components/chat/ThreadManager';
export { UserProfile } from './components/chat/UserProfile';
export { UserMenu } from './components/chat/UserMenu';
export { ChatUserContextProvider, useChatUserContext } from './components/chat/UserContext';

// Configuration
export { defaultChatConfig, mergeConfig, chatConfigPresets, validateConfig } from './config/chatConfig';
export { themeUtils, featureFlags, configUtils } from './config/chatConfig';

// Types
export type { ChatMessage, ChatThread, ChatConfig, ChatCallbacks } from './types/chatTypes';
export type { MediaAttachment, ToolCall, ChatState, ChatUserContext, MemoryItem } from './types/chatTypes';

// Utilities
export { cn } from './lib/utils';
`

---

Styling

The package ships with compiled CSS that includes all necessary styles. Import it once:

`tsx
import '@copilotz/chat-ui/styles.css';
`

$3

The component respects the dark class on your document root. Set theme programmatically:

`tsx
import { themeUtils } from '@copilotz/chat-ui';

// Apply theme
themeUtils.applyTheme('dark'); // or 'light' or 'auto'

// Get system preference
const systemTheme = themeUtils.getSystemTheme(); // 'light' | 'dark'
`

$3

Override CSS variables to customize colors (uses Tailwind/shadcn conventions):

`css
:root {
--background: 0 0% 100%;
--foreground: 222.2 84% 4.9%;
--primary: 222.2 47.4% 11.2%;
--primary-foreground: 210 40% 98%;
/ ... /
}
`

---

Requirements

- React 18+
- Tailwind CSS 4+ (for custom styling, optional)

---

Works With Any Backend

This package is purely presentational. It doesn't make API calls or manage state. You provide the data, it renders the UI.

Works with:
- Copilotz — use @copilotz/chat-adapter` for seamless integration
- OpenAI — connect to the Chat Completions API
- Anthropic — connect to Claude
- LangChain — use with any LangChain backend
- Custom backends — any API that returns messages

---

License

MIT — see LICENSE

---

Ship your agent's interface, not your UI backlog.