0
# CopilotKit React UI
1

2
CopilotKit React UI provides production-ready chat interface components for building AI-powered copilots in React applications. It offers flexible chat components (embedded, popup, and sidebar layouts), complete customization options, and seamless integration with the CopilotKit framework.
3

4
## Package Information
5

6
- **Package Name**: @copilotkit/react-ui
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @copilotkit/react-ui`
10

11
## Core Imports
12

13
```typescript
14
import {
15
  CopilotChat,
16
  CopilotPopup,
17
  CopilotSidebar,
18
  useCopilotChatSuggestions,
19
} from "@copilotkit/react-ui";
20
import "@copilotkit/react-ui/styles.css";
21
```
22

23
For CommonJS:
24

25
```javascript
26
const {
27
  CopilotChat,
28
  CopilotPopup,
29
  CopilotSidebar,
30
  useCopilotChatSuggestions,
31
} = require("@copilotkit/react-ui");
32
require("@copilotkit/react-ui/styles.css");
33
```
34

35
## Basic Usage
36

37
```typescript
38
import { CopilotKit } from "@copilotkit/react-core";
39
import { CopilotPopup } from "@copilotkit/react-ui";
40
import "@copilotkit/react-ui/styles.css";
41

42
function App() {
43
  return (
44
    <CopilotKit runtimeUrl="/api/copilotkit">
45
      <YourApp />
46
      <CopilotPopup
47
        instructions="You are a helpful assistant."
48
        labels={{
49
          title: "My Assistant",
50
          initial: "Hi! How can I help you today?",
51
        }}
52
      />
53
    </CopilotKit>
54
  );
55
}
56
```
57

58
## Architecture
59

60
CopilotKit React UI is built around several key architectural patterns:
61

62
- **Layout Components**: Three ready-to-use layouts (`CopilotChat`, `CopilotPopup`, `CopilotSidebar`) that provide different UI patterns for the same chat functionality
63
- **Component Composition**: Highly composable architecture where nearly every visual element can be replaced with custom implementations
64
- **Customization Layers**: Multiple levels of customization from simple (labels/icons) to advanced (complete component replacement)
65
- **Context-Based State**: Internal state management via React Context, with hooks for accessing chat state
66
- **Observability Hooks**: Event tracking system for monitoring user interactions and system events
67
- **Type Safety**: Full TypeScript support with comprehensive type definitions for all props and return values
68

69
## Capabilities
70

71
### Chat Interface Components
72

73
Three production-ready chat layouts for different UI patterns, all sharing the same core functionality with different presentation styles.
74

75
```typescript { .api }
76
function CopilotChat(props: CopilotChatProps): JSX.Element;
77
function CopilotPopup(props: CopilotModalProps): JSX.Element;
78
function CopilotSidebar(props: CopilotModalProps): JSX.Element;
79
```
80

81
[Chat Components](./chat-components.md)
82

83
### Message Components
84

85
Default and customizable components for rendering different message types in the chat interface.
86

87
```typescript { .api }
88
function AssistantMessage(props: AssistantMessageProps): JSX.Element;
89
function UserMessage(props: UserMessageProps): JSX.Element;
90
function ImageRenderer(props: ImageRendererProps): JSX.Element;
91
function Markdown(props: { content: string; components?: ComponentsMap }): JSX.Element;
92
```
93

94
[Message Components](./message-components.md)
95

96
### Customization System
97

98
Comprehensive customization options including icons, labels, CSS properties, and custom component renderers.
99

100
```typescript { .api }
101
interface CopilotChatIcons {
102
  openIcon?: React.ReactNode;
103
  closeIcon?: React.ReactNode;
104
  headerCloseIcon?: React.ReactNode;
105
  sendIcon?: React.ReactNode;
106
  activityIcon?: React.ReactNode;
107
  spinnerIcon?: React.ReactNode;
108
  stopIcon?: React.ReactNode;
109
  regenerateIcon?: React.ReactNode;
110
  pushToTalkIcon?: React.ReactNode;
111
  copyIcon?: React.ReactNode;
112
  thumbsUpIcon?: React.ReactNode;
113
  thumbsDownIcon?: React.ReactNode;
114
  uploadIcon?: React.ReactNode;
115
}
116

117
interface CopilotChatLabels {
118
  initial?: string | string[];
119
  title?: string;
120
  placeholder?: string;
121
  error?: string;
122
  stopGenerating?: string;
123
  regenerateResponse?: string;
124
  copyToClipboard?: string;
125
  thumbsUp?: string;
126
  thumbsDown?: string;
127
  copied?: string;
128
}
129

130
interface CopilotKitCSSProperties extends React.CSSProperties {
131
  "--copilot-kit-primary-color"?: string;
132
  "--copilot-kit-contrast-color"?: string;
133
  "--copilot-kit-background-color"?: string;
134
  "--copilot-kit-input-background-color"?: string;
135
  "--copilot-kit-secondary-color"?: string;
136
  "--copilot-kit-secondary-contrast-color"?: string;
137
  "--copilot-kit-separator-color"?: string;
138
  "--copilot-kit-muted-color"?: string;
139
  "--copilot-kit-error-background"?: string;
140
  "--copilot-kit-error-border"?: string;
141
  "--copilot-kit-error-text"?: string;
142
  "--copilot-kit-shadow-sm"?: string;
143
  "--copilot-kit-shadow-md"?: string;
144
  "--copilot-kit-shadow-lg"?: string;
145
  "--copilot-kit-dev-console-bg"?: string;
146
  "--copilot-kit-dev-console-text"?: string;
147
}
148
```
149

150
[Customization](./customization.md)
151

152
### Hooks
153

154
React hooks for chat suggestions and accessing chat context.
155

156
```typescript { .api }
157
function useCopilotChatSuggestions(
158
  config: UseCopilotChatSuggestionsConfiguration,
159
  dependencies?: any[]
160
): void;
161

162
function useChatContext(): ChatContext;
163

164
interface ChatContext {
165
  labels: Required<CopilotChatLabels>;
166
  icons: Required<CopilotChatIcons>;
167
  open: boolean;
168
  setOpen: (open: boolean) => void;
169
}
170
```
171

172
[Hooks](./hooks.md)
173

174
### TypeScript Types
175

176
Comprehensive TypeScript interfaces and types for all components and configurations.
177

178
```typescript { .api }
179
interface CopilotChatProps {
180
  instructions?: string;
181
  suggestions?: ChatSuggestions;
182
  onInProgress?: (inProgress: boolean) => void;
183
  onSubmitMessage?: (message: string) => void | Promise<void>;
184
  className?: string;
185
  // ... extensive prop interface
186
}
187

188
interface CopilotModalProps extends CopilotChatProps {
189
  defaultOpen?: boolean;
190
  clickOutsideToClose?: boolean;
191
  hitEscapeToClose?: boolean;
192
  shortcut?: string;
193
  onSetOpen?: (open: boolean) => void;
194
  // ... modal-specific props
195
}
196
```
197

198
[Types](./types.md)
199

200
### Development Console
201

202
Development tools for debugging CopilotKit applications.
203

204
```typescript { .api }
205
function CopilotDevConsole(): JSX.Element | null;
206
function shouldShowDevConsole(showDevConsole: boolean): boolean;
207
```
208

209
[Dev Console](./dev-console.md)
210