Advanced
Custom progress rendering, frontend action handlers, and advanced A2UI configuration.
This page covers two A2UI tasks:
- Show your own loading state while a surface builds.
- Handle button clicks in the browser without a new run of the agent.
Custom A2UI Progress Renderer
When using Dynamic Schema A2UI, a secondary LLM generates the UI schema and data. This takes a few seconds. During that time, CopilotKit shows a built-in progress indicator.
To replace the built-in indicator with your own component, pass it as loadingComponent in the provider's a2ui prop.
How it works
The built-in indicator is part of the A2UI surface. It shows while the surface builds, and the surface replaces it when the surface first paints. Your loadingComponent takes its place while the surface builds. It gets no props.
Implementation
Create a progress component
"use client";
export function A2UIProgress() {
return (
<div className="rounded-lg border border-gray-200 bg-gray-50 p-4">
<div className="flex items-center gap-2 text-sm text-gray-600">
<div className="h-4 w-4 animate-spin rounded-full border-2 border-gray-300 border-t-gray-600" />
<span>Building interface...</span>
</div>
</div>
);
}Pass it to the provider
"use client";
import { CopilotChat, CopilotKit } from "@copilotkit/react-core/v2";
import { A2UIProgress } from "@/components/a2ui-progress";
export default function Page() {
return (
<CopilotKit
runtimeUrl="/api/copilotkit"
a2ui={{ loadingComponent: A2UIProgress }}
>
<CopilotChat className="flex-1" />
</CopilotKit>
);
}If you also pass a catalog, put both in the same object: a2ui={{ catalog: myCatalog, loadingComponent: A2UIProgress }}.
Ask the agent for a sales dashboard. Your loader shows while the surface builds, then the dashboard replaces it.
Action Handlers
By default, each A2UI button click starts a new run of the agent. Some clicks only need to change your UI. Handle these clicks in the browser with the onAction option of createA2UIMessageRenderer.
Schema button with action context
The v0.9 A2UI schema defines buttons with an event and data-bound context fields. Components inside a repeating list use relative paths, so the context values resolve from the clicked item. The fixed-schema guide shows this button in a full schema.
{
"id": "book-button",
"component": "Button",
"child": "book-label",
"variant": "primary",
"action": {
"event": {
"name": "book_flight",
"context": {
"flightNumber": { "path": "flightNumber" },
"price": { "path": "price" }
}
}
}
}The resulting A2UIUserAction will include the resolved context:
{
name: "book_flight",
surfaceId: "flight-search-results",
sourceComponentId: "book-button",
timestamp: "2025-01-01T00:00:00.000Z",
context: { flightNumber: "AA100", price: "$350" },
}onAction interceptor
Pass onAction to the exported renderer factory to handle an action in the browser. Return null after handling the action locally; return undefined to forward it unchanged to the agent:
import {
a2uiDefaultTheme,
createA2UIMessageRenderer,
type A2UIUserAction,
} from "@copilotkit/react-core/v2";
import { myCatalog } from "./a2ui/catalog"; // the catalog you pass to the provider
const A2UIMessageRenderer = createA2UIMessageRenderer({
theme: a2uiDefaultTheme,
catalog: myCatalog,
onAction: (action: A2UIUserAction) => {
if (action.name === "book_flight") {
console.info("Booking requested", action.context);
return null;
}
return undefined;
},
});
const activityRenderers = [A2UIMessageRenderer];If you need this custom onAction behavior, pass the returned renderer in the provider's renderActivityMessages prop. User-provided renderers take precedence over the provider's built-in A2UI renderer. Your renderer replaces the built-in one, so give it the same catalog as the provider. Without catalog, it uses the basic catalog and your custom components do not render.
<CopilotKit
runtimeUrl="/api/copilotkit"
a2ui={{ catalog: myCatalog }}
renderActivityMessages={activityRenderers}
>
{/* ... */}
</CopilotKit>Forward a modified action
An interceptor can return a modified exported A2UIUserAction; the renderer forwards that action to the agent:
const A2UIMessageRenderer = createA2UIMessageRenderer({
theme: a2uiDefaultTheme,
catalog: myCatalog,
onAction: (action) => {
if (action.name !== "book_flight") return;
return {
...action,
context: {
...(action.context ?? {}),
source: "a2ui",
},
};
},
});Current action flow
The renderer runs onAction before it forwards an action:
- Returning
nullhandles the action in the browser and skips the agent. - Returning an
A2UIUserActionforwards that modified action. - Returning
undefinedforwards the original action.
The action passed to onAction does not include dataContextPath. Put the values that the callback needs in context.
Types reference
| Type | Description |
|---|---|
A2UIUserAction | Dispatched action: { name, surfaceId, sourceComponentId, timestamp, context? } |
A2UIActionInterceptor | (action, forward) => A2UIUserAction | null | void | Promise<void | A2UIUserAction | null> (exported interceptor type) |
createA2UIMessageRenderer | Exported factory that accepts theme and optional catalog, loadingComponent, recovery, and onAction |
How is this guide?