Open History to see the last commit
1---
2title: Showing Code Mode in the UI
3id: code-mode-client-integration
4order: 2
5description: "Stream Code Mode execution events to your React app — console output, external calls, and results as they happen, via onCustomEvent."
6keywords:
7 - tanstack ai
8 - code mode
9 - react ui
10 - custom events
11 - onCustomEvent
12 - streaming ui
13 - execution progress
14---
15
16You have [Code Mode](./code-mode) working on your server — the LLM writes and executes TypeScript, and you get results back. But your users see nothing while the sandbox runs. By the end of this guide, your React app will show real-time execution progress: console output, external function calls, and final results as they stream in.
17
18## How events reach the client
19
20When code runs inside the sandbox, Code Mode emits **custom events** through the AG-UI streaming protocol. These events travel alongside normal chat chunks (text, tool calls) and arrive in your client via the `onCustomEvent` callback.
21
22The events emitted during each `execute_typescript` call:
23
24| Event | When | Key fields |
25|-------|------|------------|
26| `code_mode:execution_started` | Sandbox begins executing | `timestamp`, `codeLength` |
27| `code_mode:console` | Each `console.log/error/warn/info` | `level`, `message`, `timestamp` |
28| `code_mode:external_call` | Before an `external_*` function runs | `function`, `args`, `timestamp` |
29| `code_mode:external_result` | After a successful `external_*` call | `function`, `result`, `duration` |
30| `code_mode:external_error` | When an `external_*` call fails | `function`, `error`, `duration` |
31
32Every event includes a `toolCallId` that ties it to the specific `execute_typescript` tool call, so you can render events alongside the right message.
33
34## Listening to events with useChat
35
36Pass an `onCustomEvent` callback to `useChat`. The callback receives the event type, payload, and a context object with the `toolCallId`:
37
38```tsx group=code-mode-client
39import { useCallback, useRef, useState } from "react";
40import { useChat, fetchServerSentEvents } from "@tanstack/ai-react";
41
42interface VMEvent {
43 id: string;
44 eventType: string;
45 data: unknown;
46 timestamp: number;
47}
48
49export function CodeModeChat() {
50 const [toolCallEvents, setToolCallEvents] = useState<
51 Map<string, Array<VMEvent>>
52 >(new Map());
53 const eventIdCounter = useRef(0);
54
55 const handleCustomEvent = useCallback(
56 (
57 eventType: string,
58 data: unknown,
59 context: { toolCallId?: string },
60 ) => {
61 const { toolCallId } = context;
62 if (!toolCallId) return;
63
64 const event: VMEvent = {
65 id: `event-${eventIdCounter.current++}`,
66 eventType,
67 data,
68 timestamp: Date.now(),
69 };
70
71 setToolCallEvents((prev) => {
72 const next = new Map(prev);
73 const events = next.get(toolCallId) || [];
74 next.set(toolCallId, [...events, event]);
75 return next;
76 });
77 },
78 [],
79 );
80
81 const { messages, sendMessage, isLoading } = useChat({
82 connection: fetchServerSentEvents("/api/chat"),
83 onCustomEvent: handleCustomEvent,
84 });
85
86 // Render messages with events — see next section
87}
88```
89
90Events are keyed by `toolCallId` so each `execute_typescript` call gets its own event timeline.
91
92## Rendering execution progress
93
94When rendering messages, check for `execute_typescript` tool calls and display their events:
95
96```tsx group=code-mode-client
97function MessageList({
98 messages,
99 toolCallEvents,
100}: {
101 messages: Array<{ id: string; role: string; parts: Array<any> }>;
102 toolCallEvents: Map<string, Array<VMEvent>>;
103}) {
104 return (
105 <div>
106 {messages.map((message) => (
107 <div key={message.id}>
108 {message.parts.map((part) => {
109 if (part.type === "text") {
110 return <p key={part.id}>{part.content}</p>;
111 }
112
113 if (
114 part.type === "tool-call" &&
115 part.name === "execute_typescript"
116 ) {
117 const events = toolCallEvents.get(part.id) || [];
118 const result = part.output;
119
120 return (
121 <div key={part.id}>
122 <CodeExecutionPanel
123 code={part.input?.typescriptCode}
124 events={events}
125 result={result}
126 isRunning={!result}
127 />
128 </div>
129 );
130 }
131
132 return null;
133 })}
134 </div>
135 ))}
136 </div>
137 );
138}
139```
140
141## Building an execution panel
142
143Here's a complete `CodeExecutionPanel` component that shows the generated code, live event stream, and final result:
144
145```tsx group=code-mode-client
146function CodeExecutionPanel({
147 code,
148 events,
149 result,
150 isRunning,
151}: {
152 code?: string;
153 events: Array<VMEvent>;
154 result?: { success: boolean; result?: unknown; logs?: string[]; error?: { message: string } };
155 isRunning: boolean;
156}) {
157 return (
158 <div className="border rounded-lg overflow-hidden my-2">
159 {/* Generated code */}
160 {code && (
161 <details open>
162 <summary className="px-3 py-2 bg-gray-100 font-mono text-sm cursor-pointer">
163 TypeScript code
164 </summary>
165 <pre className="p-3 text-sm overflow-x-auto bg-gray-50">
166 <code>{code}</code>
167 </pre>
168 </details>
169 )}
170
171 {/* Live event stream */}
172 {events.length > 0 && (
173 <div className="border-t px-3 py-2">
174 <div className="text-xs font-semibold text-gray-500 mb-1">
175 Execution log
176 </div>
177 <div className="space-y-1 font-mono text-xs">
178 {events.map((event) => (
179 <EventLine key={event.id} event={event} />
180 ))}
181 {isRunning && (
182 <div className="text-blue-500 animate-pulse">Running...</div>
183 )}
184 </div>
185 </div>
186 )}
187
188 {/* Final result */}
189 {result && (
190 <div
191 className={`border-t px-3 py-2 text-sm ${
192 result.success ? "bg-green-50" : "bg-red-50"
193 }`}
194 >
195 {result.error && (
196 <div className="text-red-700">Error: {result.error.message}</div>
197 )}
198 {result.logs && result.logs.length > 0 && (
199 <pre className="text-gray-600 text-xs mt-1">
200 {result.logs.join("\n")}
201 </pre>
202 )}
203 {result.success && result.result !== undefined && (
204 <pre className="text-green-800 text-xs mt-1">
205 {JSON.stringify(result.result, null, 2)}
206 </pre>
207 )}
208 </div>
209 )}
210 </div>
211 );
212}
213
214function isRecord(value: unknown): value is Record<string, unknown> {
215 return typeof value === "object" && value !== null;
216}
217
218function EventLine({ event }: { event: VMEvent }) {
219 if (!isRecord(event.data)) return null;
220 const data = event.data;
221
222 switch (event.eventType) {
223 case "code_mode:console":
224 return (
225 <div
226 className={
227 data.level === "error"
228 ? "text-red-600"
229 : data.level === "warn"
230 ? "text-yellow-600"
231 : "text-gray-600"
232 }
233 >
234 [{String(data.level)}] {String(data.message)}
235 </div>
236 );
237
238 case "code_mode:external_call":
239 return (
240 <div className="text-amber-600">
241 → {String(data.function)}(
242 {JSON.stringify(data.args)})
243 </div>
244 );
245
246 case "code_mode:external_result":
247 return (
248 <div className="text-green-600">
249 ← {String(data.function)} ({String(data.duration)}ms)
250 </div>
251 );
252
253 case "code_mode:external_error":
254 return (
255 <div className="text-red-600">
256 ✗ {String(data.function)}: {String(data.error)}
257 </div>
258 );
259
260 case "code_mode:execution_started":
261 return <div className="text-cyan-600">▶ Execution started</div>;
262
263 default:
264 return (
265 <div className="text-gray-400">
266 {event.eventType}: {JSON.stringify(data)}
267 </div>
268 );
269 }
270}
271```
272
273This gives you:
274- A collapsible code block showing the TypeScript the model wrote
275- A live event log showing console output, external function calls with arguments, results with durations, and errors
276- A status-colored result panel with logs and the return value
277
278## Adapting for other frameworks
279
280The `onCustomEvent` callback is available through `ChatClient` from `@tanstack/ai-client`, which all framework integrations use under the hood. In Solid, Vue, or Svelte, pass `onCustomEvent` in the same way you pass it to `useChat` in React — the callback signature is identical:
281
282```typescript ignore
283(eventType: string, data: unknown, context: { toolCallId?: string }) => void
284```
285
286See [Code Mode](./code-mode) for setting up the server side, and [Code Mode with Skills](./code-mode-with-skills) for adding persistent skill libraries.