0
# Hooks
1

2
React hooks for configuring chat suggestions and accessing chat context within CopilotKit components.
3

4
## Capabilities
5

6
### useCopilotChatSuggestions
7

8
Hook for configuring automatic chat suggestions. Registers suggestion configuration with the CopilotKit context, and suggestions are generated by AI based on provided instructions.
9

10
```typescript { .api }
11
/**
12
 * Configure automatic chat suggestions generated by AI
13
 * @param config - Suggestion configuration with instructions and constraints
14
 * @param dependencies - Optional dependency array for re-registration
15
 * @experimental Interface may change in future versions
16
 */
17
function useCopilotChatSuggestions(
18
  config: UseCopilotChatSuggestionsConfiguration,
19
  dependencies?: any[]
20
): void;
21

22
interface UseCopilotChatSuggestionsConfiguration {
23
  /** Instructions for GPT to generate relevant suggestions */
24
  instructions: string;
25

26
  /** Minimum number of suggestions to generate (default: 1) */
27
  minSuggestions?: number;
28

29
  /** Maximum number of suggestions to generate (default: 3) */
30
  maxSuggestions?: number;
31

32
  /** Whether suggestions are available (default: "enabled") */
33
  available?: "enabled" | "disabled";
34

35
  /** Optional CSS class for suggestions container */
36
  className?: string;
37
}
38
```
39

40
**Usage Example - Basic Suggestions:**
41

42
```typescript
43
import { CopilotPopup, useCopilotChatSuggestions } from "@copilotkit/react-ui";
44
import "@copilotkit/react-ui/styles.css";
45

46
function MyApp() {
47
  // Configure suggestions based on current context
48
  useCopilotChatSuggestions({
49
    instructions: "Suggest helpful questions the user might want to ask about their data analysis tasks.",
50
    minSuggestions: 2,
51
    maxSuggestions: 4,
52
  });
53

54
  return (
55
    <div>
56
      <DataAnalysisPanel />
57
      <CopilotPopup suggestions="auto" />
58
    </div>
59
  );
60
}
61
```
62

63
**Usage Example - Context-Aware Suggestions:**
64

65
```typescript
66
import { CopilotChat, useCopilotChatSuggestions } from "@copilotkit/react-ui";
67
import { useState } from "react";
68

69
function DocumentEditor() {
70
  const [currentDocument, setCurrentDocument] = useState<Document | null>(null);
71

72
  // Update suggestions when document changes
73
  useCopilotChatSuggestions(
74
    {
75
      instructions: currentDocument
76
        ? `Suggest relevant actions for editing a document titled "${currentDocument.title}" with ${currentDocument.wordCount} words. Suggest things like summarizing, improving clarity, checking grammar, or extracting key points.`
77
        : "Suggest general document editing tasks like creating a new document, opening a file, or learning about features.",
78
      minSuggestions: 3,
79
      maxSuggestions: 5,
80
    },
81
    [currentDocument?.id] // Re-register when document changes
82
  );
83

84
  return (
85
    <div className="editor-layout">
86
      <Editor document={currentDocument} onChange={setCurrentDocument} />
87
      <CopilotChat suggestions="auto" />
88
    </div>
89
  );
90
}
91
```
92

93
**Usage Example - Conditional Suggestions:**
94

95
```typescript
96
import { CopilotPopup, useCopilotChatSuggestions } from "@copilotkit/react-ui";
97

98
function ShoppingCart({ items }: { items: CartItem[] }) {
99
  const hasItems = items.length > 0;
100

101
  useCopilotChatSuggestions(
102
    {
103
      instructions: hasItems
104
        ? `User has ${items.length} items in cart. Suggest actions like applying discounts, checking out, or finding similar products.`
105
        : "Cart is empty. Suggest browsing categories, viewing deals, or searching for products.",
106
      minSuggestions: 2,
107
      maxSuggestions: 3,
108
      available: "enabled",
109
    },
110
    [items.length]
111
  );
112

113
  return (
114
    <div>
115
      <CartDisplay items={items} />
116
      <CopilotPopup suggestions="auto" />
117
    </div>
118
  );
119
}
120
```
121

122
**Usage Example - Disabled Suggestions:**
123

124
```typescript
125
import { CopilotChat, useCopilotChatSuggestions } from "@copilotkit/react-ui";
126

127
function RestrictedArea({ userRole }: { userRole: string }) {
128
  // Disable suggestions for certain user roles
129
  useCopilotChatSuggestions(
130
    {
131
      instructions: "Suggest general help topics.",
132
      available: userRole === "admin" ? "enabled" : "disabled",
133
    },
134
    [userRole]
135
  );
136

137
  return <CopilotChat suggestions="auto" />;
138
}
139
```
140

141
### useChatContext
142

143
Hook to access the chat context. Provides access to labels, icons, and open state. Must be used within a ChatContextProvider (automatically provided by CopilotChat, CopilotPopup, and CopilotSidebar).
144

145
```typescript { .api }
146
/**
147
 * Access chat context including labels, icons, and open state
148
 * @returns Chat context object
149
 * @throws Error if used outside ChatContextProvider
150
 */
151
function useChatContext(): ChatContext;
152

153
interface ChatContext {
154
  /** All label overrides with defaults applied */
155
  labels: Required<CopilotChatLabels>;
156

157
  /** All icon overrides with defaults applied */
158
  icons: Required<CopilotChatIcons>;
159

160
  /** Whether chat is currently open (for popup/sidebar) */
161
  open: boolean;
162

163
  /** Function to set open state */
164
  setOpen: (open: boolean) => void;
165
}
166

167
interface CopilotChatLabels {
168
  initial?: string | string[];
169
  title?: string;
170
  placeholder?: string;
171
  error?: string;
172
  stopGenerating?: string;
173
  regenerateResponse?: string;
174
  copyToClipboard?: string;
175
  thumbsUp?: string;
176
  thumbsDown?: string;
177
  copied?: string;
178
}
179

180
interface CopilotChatIcons {
181
  openIcon?: React.ReactNode;
182
  closeIcon?: React.ReactNode;
183
  headerCloseIcon?: React.ReactNode;
184
  sendIcon?: React.ReactNode;
185
  activityIcon?: React.ReactNode;
186
  spinnerIcon?: React.ReactNode;
187
  stopIcon?: React.ReactNode;
188
  regenerateIcon?: React.ReactNode;
189
  pushToTalkIcon?: React.ReactNode;
190
  copyIcon?: React.ReactNode;
191
  thumbsUpIcon?: React.ReactNode;
192
  thumbsDownIcon?: React.ReactNode;
193
  uploadIcon?: React.ReactNode;
194
}
195
```
196

197
**Usage Example - Custom Component Using Context:**
198

199
```typescript
200
import { useChatContext } from "@copilotkit/react-ui";
201

202
function CustomChatHeader() {
203
  const { labels, icons, open, setOpen } = useChatContext();
204

205
  return (
206
    <header className="chat-header">
207
      <h2>{labels.title}</h2>
208
      <button onClick={() => setOpen(!open)}>
209
        {open ? icons.closeIcon : icons.openIcon}
210
      </button>
211
    </header>
212
  );
213
}
214
```
215

216
**Usage Example - Custom Button Component:**
217

218
```typescript
219
import { useChatContext } from "@copilotkit/react-ui";
220

221
function CustomToggleButton() {
222
  const { open, setOpen, labels, icons } = useChatContext();
223

224
  return (
225
    <button
226
      onClick={() => setOpen(!open)}
227
      className={`toggle-btn ${open ? "open" : "closed"}`}
228
      aria-label={open ? "Close chat" : "Open chat"}
229
    >
230
      {open ? icons.closeIcon : icons.openIcon}
231
      <span>{open ? "Close" : labels.title}</span>
232
    </button>
233
  );
234
}
235
```
236

237
**Usage Example - Status Indicator:**
238

239
```typescript
240
import { useChatContext } from "@copilotkit/react-ui";
241

242
function ChatStatusIndicator() {
243
  const { open, labels } = useChatContext();
244

245
  return (
246
    <div className="status-indicator">
247
      <div className={`status-dot ${open ? "active" : "inactive"}`} />
248
      <span>
249
        {labels.title} is {open ? "open" : "closed"}
250
      </span>
251
    </div>
252
  );
253
}
254
```
255

256
**Usage Example - Custom Input with Context:**
257

258
```typescript
259
import { useChatContext, InputProps } from "@copilotkit/react-ui";
260
import { useState } from "react";
261

262
function CustomInputWithContext({ inProgress, onSend }: InputProps) {
263
  const { labels, icons } = useChatContext();
264
  const [text, setText] = useState("");
265

266
  const handleSubmit = async (e: React.FormEvent) => {
267
    e.preventDefault();
268
    if (!text.trim() || inProgress) return;
269
    await onSend(text);
270
    setText("");
271
  };
272

273
  return (
274
    <form onSubmit={handleSubmit}>
275
      <input
276
        type="text"
277
        value={text}
278
        onChange={(e) => setText(e.target.value)}
279
        placeholder={labels.placeholder}
280
        disabled={inProgress}
281
      />
282
      <button type="submit" disabled={!text.trim() || inProgress}>
283
        {icons.sendIcon}
284
      </button>
285
    </form>
286
  );
287
}
288
```
289

290
**Usage Example - Programmatic Control:**
291

292
```typescript
293
import { CopilotPopup, useChatContext } from "@copilotkit/react-ui";
294
import { useEffect } from "react";
295

296
function AppWithProgrammaticControl() {
297
  return (
298
    <CopilotPopup instructions="You are helpful.">
299
      <AppContent />
300
    </CopilotPopup>
301
  );
302
}
303

304
function AppContent() {
305
  const { setOpen } = useChatContext();
306

307
  // Open chat when user is inactive
308
  useEffect(() => {
309
    const timeout = setTimeout(() => {
310
      setOpen(true);
311
    }, 30000); // Open after 30 seconds
312

313
    return () => clearTimeout(timeout);
314
  }, [setOpen]);
315

316
  const handleHelpClick = () => {
317
    // Open chat when help button is clicked
318
    setOpen(true);
319
  };
320

321
  return (
322
    <div>
323
      <button onClick={handleHelpClick}>Need Help?</button>
324
      <YourAppContent />
325
    </div>
326
  );
327
}
328
```
329

330
### ChatContextProvider
331

332
Provider component for chat context. Automatically used internally by CopilotChat, CopilotPopup, and CopilotSidebar. Generally not used directly by applications.
333

334
```typescript { .api }
335
/**
336
 * Provider for chat context - automatically used by chat components
337
 * @param props - Labels, icons, and open state
338
 * @returns Provider component wrapping children
339
 * @internal Typically not used directly by applications
340
 *
341
 * Note: ChatContextProvider and ChatContextProps are internal and not exported
342
 * from @copilotkit/react-ui. This documentation is provided for reference only.
343
 */
344
function ChatContextProvider(props: ChatContextProps): JSX.Element;
345

346
interface ChatContextProps {
347
  /** Label overrides */
348
  labels?: CopilotChatLabels;
349

350
  /** Icon overrides */
351
  icons?: CopilotChatIcons;
352

353
  /** Current open state */
354
  open: boolean;
355

356
  /** Function to update open state */
357
  setOpen: (open: boolean) => void;
358

359
  /** Child components */
360
  children?: React.ReactNode;
361
}
362
```
363

364
**Usage Example - Manual Context Provider (Advanced):**
365

366
```typescript
367
import { ChatContextProvider, useChatContext } from "@copilotkit/react-ui";
368
import { useState } from "react";
369

370
// Rarely needed - chat components provide this automatically
371
function ManualContextSetup() {
372
  const [open, setOpen] = useState(false);
373

374
  return (
375
    <ChatContextProvider
376
      open={open}
377
      setOpen={setOpen}
378
      labels={{
379
        title: "Custom Chat",
380
        placeholder: "Type here...",
381
      }}
382
      icons={{
383
        sendIcon: "→",
384
        closeIcon: "×",
385
      }}
386
    >
387
      <CustomChatImplementation />
388
    </ChatContextProvider>
389
  );
390
}
391

392
function CustomChatImplementation() {
393
  const context = useChatContext();
394
  // Build custom chat UI using context
395
  return <div>{/* Custom implementation */}</div>;
396
}
397
```
398