0
# Chat Interface Components
1

2
Three production-ready chat layouts providing different UI patterns for integrating AI assistants into React applications. All layouts share the same core functionality with different presentation styles.
3

4
## Capabilities
5

6
### CopilotChat
7

8
Main embedded chat component for displaying a chat interface directly in your application. Provides a fully-featured chat panel with message history, input controls, and customizable UI elements.
9

10
```typescript { .api }
11
/**
12
 * Main chatbot panel component for embedding directly in your application
13
 * @param props - Configuration props for the chat interface
14
 * @returns Rendered chat component
15
 */
16
function CopilotChat(props: CopilotChatProps): JSX.Element;
17

18
interface CopilotChatProps {
19
  /** Custom instructions for the system message */
20
  instructions?: string;
21

22
  /** Suggestion behavior: "auto" (AI-generated), "manual" (programmatic), or static array */
23
  suggestions?: ChatSuggestions;
24

25
  /** Callback when generation state changes */
26
  onInProgress?: (inProgress: boolean) => void;
27

28
  /** Callback when user submits a message */
29
  onSubmitMessage?: (message: string) => void | Promise<void>;
30

31
  /** Custom stop generation handler */
32
  onStopGeneration?: OnStopGeneration;
33

34
  /** Custom reload/regenerate handler */
35
  onReloadMessages?: OnReloadMessages;
36

37
  /** Callback when message is regenerated */
38
  onRegenerate?: (messageId: string) => void;
39

40
  /** Callback when message is copied to clipboard */
41
  onCopy?: (message: string) => void;
42

43
  /** Callback for positive feedback */
44
  onThumbsUp?: (message: Message) => void;
45

46
  /** Callback for negative feedback */
47
  onThumbsDown?: (message: Message) => void;
48

49
  /** Custom markdown component renderers */
50
  markdownTagRenderers?: ComponentsMap;
51

52
  /** Custom icon overrides */
53
  icons?: CopilotChatIcons;
54

55
  /** Custom label/text overrides */
56
  labels?: CopilotChatLabels;
57

58
  /** Enable image upload functionality (default: false) */
59
  imageUploadsEnabled?: boolean;
60

61
  /** File input accept attribute (default: "image/*") */
62
  inputFileAccept?: string;
63

64
  /** Override system message generation */
65
  makeSystemMessage?: SystemMessageFunction;
66

67
  /** Disable system message entirely */
68
  disableSystemMessage?: boolean;
69

70
  /** Custom assistant message component */
71
  AssistantMessage?: React.ComponentType<AssistantMessageProps>;
72

73
  /** Custom user message component */
74
  UserMessage?: React.ComponentType<UserMessageProps>;
75

76
  /** Custom error message component */
77
  ErrorMessage?: React.ComponentType<ErrorMessageProps>;
78

79
  /** Custom messages container component */
80
  Messages?: React.ComponentType<MessagesProps>;
81

82
  /** Custom message renderer */
83
  RenderMessage?: React.ComponentType<RenderMessageProps>;
84

85
  /** Custom suggestions list renderer */
86
  RenderSuggestionsList?: React.ComponentType<RenderSuggestionsListProps>;
87

88
  /** Custom input component */
89
  Input?: React.ComponentType<InputProps>;
90

91
  /** Custom image renderer */
92
  ImageRenderer?: React.ComponentType<ImageRendererProps>;
93

94
  /** Additional CSS class */
95
  className?: string;
96

97
  /** Child elements */
98
  children?: React.ReactNode;
99

100
  /** Hide the stop generation button */
101
  hideStopButton?: boolean;
102

103
  /** Event tracking hooks (requires publicApiKey in CopilotKit provider) */
104
  observabilityHooks?: CopilotObservabilityHooks;
105

106
  /** Custom error renderer */
107
  renderError?: (error: {
108
    message: string;
109
    operation?: string;
110
    timestamp: number;
111
    onDismiss: () => void;
112
    onRetry?: () => void;
113
  }) => React.ReactNode;
114

115
  /** Error handler for debugging */
116
  onError?: CopilotErrorHandler;
117
}
118

119
type ChatSuggestions = "auto" | "manual" | SuggestionItem[];
120

121
interface SuggestionItem {
122
  title: string;
123
  message: string;
124
  partial?: boolean;
125
  className?: string;
126
}
127
```
128

129
**Usage Example:**
130

131
```typescript
132
import { CopilotChat } from "@copilotkit/react-ui";
133
import "@copilotkit/react-ui/styles.css";
134

135
function MyApp() {
136
  return (
137
    <div className="app-container">
138
      <main className="content">
139
        {/* Your app content */}
140
      </main>
141
      <aside className="chat-panel">
142
        <CopilotChat
143
          instructions="You are a helpful assistant for project management."
144
          labels={{
145
            title: "Project Assistant",
146
            initial: "Hi! I can help you manage your projects.",
147
            placeholder: "Ask about your projects...",
148
          }}
149
          onSubmitMessage={(message) => {
150
            console.log("User sent:", message);
151
          }}
152
          onThumbsUp={(message) => {
153
            console.log("User liked:", message.id);
154
          }}
155
        />
156
      </aside>
157
    </div>
158
  );
159
}
160
```
161

162
### CopilotPopup
163

164
Popup/modal version of the chat interface that displays as a floating window. Can be opened and closed by users, with keyboard shortcuts and customizable triggers.
165

166
```typescript { .api }
167
/**
168
 * Popup/modal version of the chat interface
169
 * @param props - Configuration props extending CopilotChatProps with modal-specific options
170
 * @returns Rendered popup component with toggle button
171
 */
172
function CopilotPopup(props: CopilotModalProps): JSX.Element;
173

174
interface CopilotModalProps extends CopilotChatProps {
175
  /** Whether popup is open by default (default: false) */
176
  defaultOpen?: boolean;
177

178
  /** Close popup when clicking outside (default: true) */
179
  clickOutsideToClose?: boolean;
180

181
  /** Close popup when pressing Escape (default: true) */
182
  hitEscapeToClose?: boolean;
183

184
  /** Keyboard shortcut to toggle popup (default: "/") */
185
  shortcut?: string;
186

187
  /** Callback when open state changes */
188
  onSetOpen?: (open: boolean) => void;
189

190
  /** Custom window/modal component */
191
  Window?: React.ComponentType<WindowProps>;
192

193
  /** Custom toggle button component */
194
  Button?: React.ComponentType<ButtonProps>;
195

196
  /** Custom header component */
197
  Header?: React.ComponentType<HeaderProps>;
198
}
199

200
interface WindowProps {
201
  clickOutsideToClose: boolean;
202
  hitEscapeToClose: boolean;
203
  shortcut: string;
204
  children?: React.ReactNode;
205
}
206

207
interface ButtonProps {
208
  // Can be extended with custom props
209
}
210

211
interface HeaderProps {
212
  // Can be extended with custom props
213
}
214
```
215

216
**Usage Example:**
217

218
```typescript
219
import { CopilotPopup } from "@copilotkit/react-ui";
220
import "@copilotkit/react-ui/styles.css";
221

222
function App() {
223
  const [isOpen, setIsOpen] = React.useState(false);
224

225
  return (
226
    <div>
227
      <YourAppContent />
228
      <CopilotPopup
229
        instructions="You are a helpful coding assistant."
230
        defaultOpen={false}
231
        shortcut="/"
232
        clickOutsideToClose={true}
233
        hitEscapeToClose={true}
234
        onSetOpen={setIsOpen}
235
        labels={{
236
          title: "Code Assistant",
237
          initial: "Hi! Press '/' to ask me anything about coding.",
238
        }}
239
        icons={{
240
          openIcon: <CustomOpenIcon />,
241
          closeIcon: <CustomCloseIcon />,
242
        }}
243
      />
244
    </div>
245
  );
246
}
247
```
248

249
### CopilotSidebar
250

251
Sidebar version of the chat interface that slides in from the side. Wraps your content and adjusts layout when the sidebar is expanded.
252

253
```typescript { .api }
254
/**
255
 * Sidebar version of the chat interface that slides in/out from the side
256
 * @param props - Configuration props same as CopilotModalProps
257
 * @returns Rendered sidebar with content wrapper
258
 */
259
function CopilotSidebar(props: CopilotModalProps): JSX.Element;
260
```
261

262
**Usage Example:**
263

264
```typescript
265
import { CopilotSidebar } from "@copilotkit/react-ui";
266
import "@copilotkit/react-ui/styles.css";
267

268
function App() {
269
  return (
270
    <CopilotSidebar
271
      instructions="You are a helpful document assistant."
272
      defaultOpen={false}
273
      labels={{
274
        title: "Document Helper",
275
        initial: "Need help with your documents?",
276
      }}
277
    >
278
      <div className="main-content">
279
        {/* Your app content - automatically adjusts when sidebar opens */}
280
        <h1>My Document Editor</h1>
281
        <Editor />
282
      </div>
283
    </CopilotSidebar>
284
  );
285
}
286
```
287

288
### Observability Hooks
289

290
Event tracking system for monitoring user interactions and chat behavior. Requires `publicApiKey` to be set in the CopilotKit provider.
291

292
```typescript { .api }
293
interface CopilotObservabilityHooks {
294
  /** Called when user sends a message */
295
  onMessageSent?: (message: string) => void;
296

297
  /** Called when chat is closed/minimized */
298
  onChatMinimized?: () => void;
299

300
  /** Called when chat is opened/expanded */
301
  onChatExpanded?: () => void;
302

303
  /** Called when message is regenerated */
304
  onMessageRegenerated?: (messageId: string) => void;
305

306
  /** Called when message is copied to clipboard */
307
  onMessageCopied?: (content: string) => void;
308

309
  /** Called when user provides feedback */
310
  onFeedbackGiven?: (messageId: string, type: "thumbsUp" | "thumbsDown") => void;
311

312
  /** Called when generation starts */
313
  onChatStarted?: () => void;
314

315
  /** Called when generation stops */
316
  onChatStopped?: () => void;
317

318
  /** Called on errors */
319
  onError?: (errorEvent: CopilotErrorEvent) => void;
320
}
321
```
322

323
**Usage Example:**
324

325
```typescript
326
<CopilotPopup
327
  instructions="You are a helpful assistant."
328
  observabilityHooks={{
329
    onMessageSent: (message) => {
330
      analytics.track("chat_message_sent", { message });
331
    },
332
    onChatExpanded: () => {
333
      analytics.track("chat_opened");
334
    },
335
    onChatMinimized: () => {
336
      analytics.track("chat_closed");
337
    },
338
    onFeedbackGiven: (messageId, type) => {
339
      analytics.track("chat_feedback", { messageId, type });
340
    },
341
  }}
342
/>
343
```
344

345
### Custom Stop and Reload Handlers
346

347
Advanced handlers for customizing stop generation and message regeneration behavior.
348

349
**Note:** These types are not exported from the package. Use the type signatures shown below or infer types from the prop definitions.
350

351
```typescript { .api }
352
type OnStopGeneration = (args: OnStopGenerationArguments) => void;
353

354
interface OnStopGenerationArguments {
355
  /** Currently executing agent name */
356
  currentAgentName: string | undefined;
357

358
  /** Current message array */
359
  messages: Message[];
360

361
  /** Function to update messages */
362
  setMessages: (messages: Message[]) => void;
363

364
  /** Default stop generation function */
365
  stopGeneration: () => void;
366

367
  /** Restart the current agent */
368
  restartCurrentAgent: () => void;
369

370
  /** Stop the current agent */
371
  stopCurrentAgent: () => void;
372

373
  /** Run the current agent with optional hint */
374
  runCurrentAgent: (hint?: HintFunction) => Promise<void>;
375

376
  /** Set agent state */
377
  setCurrentAgentState: (state: any) => void;
378
}
379

380
type OnReloadMessages = (args: OnReloadMessagesArguments) => void;
381

382
interface OnReloadMessagesArguments extends OnStopGenerationArguments {
383
  /** ID of message to regenerate */
384
  messageId: string;
385
}
386
```
387

388
**Usage Example:**
389

390
```typescript
391
<CopilotChat
392
  onStopGeneration={(args) => {
393
    // Custom stop logic
394
    console.log("Stopping agent:", args.currentAgentName);
395
    args.stopGeneration();
396
    // Custom cleanup
397
    cleanupResources();
398
  }}
399
  onReloadMessages={(args) => {
400
    // Custom reload logic
401
    console.log("Reloading message:", args.messageId);
402
    // Filter out messages after the one being regenerated
403
    const index = args.messages.findIndex((m) => m.id === args.messageId);
404
    args.setMessages(args.messages.slice(0, index + 1));
405
    // Run agent again
406
    args.runCurrentAgent();
407
  }}
408
/>
409
```
410