@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

npm install @copilotz/chat-ui

Import the styles once in your app:

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

Drop in the component:

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

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

  return (
    <ChatUI
      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

Messages That Do More

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.

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',
  }],
};

Input That Works

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

Thread Management

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.

User Profile

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.

Agent Selector

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.

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

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

Configuration

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

Presets

Start with a preset and override what you need:

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

// Minimal: no threads, no file upload, compact mode
<ChatUI config={chatConfigPresets.minimal} />

// Full: all features enabled, timestamps, word count
<ChatUI config={chatConfigPresets.full} />

// Developer: tool calls visible, timestamps, file upload
<ChatUI config={chatConfigPresets.developer} />

// Customer Support: threads, file upload, no message editing
<ChatUI config={chatConfigPresets.customer_support} />

Custom Configuration

<ChatUI
  config={{
    branding: {
      title: 'Acme Assistant',
      subtitle: 'How can I help you today?',
      logo: <AcmeLogo />,
      avatar: <BotIcon />,
    },
    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,
    },
  }}
/>

Custom Right Sidebar

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

<ChatUI
  config={{
    customComponent: {
      label: 'Profile',
      icon: <User />,
      component: ({ onClose, isMobile }) => (
        <div className="p-4">
          <h2>User Profile</h2>
          <button onClick={onClose}>Close</button>
        </div>
      ),
    },
  }}
/>

Callbacks

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

<ChatUI
  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

ChatUI

| 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 |

ChatMessage

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

MediaAttachment

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 };

ToolCall

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

AgentOption

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

Exports

// 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:

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

Theming

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

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

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

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

CSS Variables

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

: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