Advanced

Custom progress rendering, frontend action handlers, and advanced A2UI configuration.

This page covers two A2UI tasks:

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

src/components/a2ui-progress.tsx
"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

src/app/page.tsx
"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:

  1. Returning null handles the action in the browser and skips the agent.
  2. Returning an A2UIUserAction forwards that modified action.
  3. Returning undefined forwards the original action.

The action passed to onAction does not include dataContextPath. Put the values that the callback needs in context.

Types reference

TypeDescription
A2UIUserActionDispatched action: { name, surfaceId, sourceComponentId, timestamp, context? }
A2UIActionInterceptor(action, forward) => A2UIUserAction | null | void | Promise<void | A2UIUserAction | null> (exported interceptor type)
createA2UIMessageRendererExported factory that accepts theme and optional catalog, loadingComponent, recovery, and onAction

How is this guide?