# Advanced

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

This page covers two A2UI tasks:

- [Show your own loading state](#custom-a2ui-progress-renderer) while a surface builds.
- [Handle button clicks in the browser](#action-handlers) without a new run of the agent.

## Custom A2UI Progress Renderer [#custom-a2ui-progress-renderer]

When using [Dynamic Schema A2UI](/generative-ui/a2ui/dynamic-schema), 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 [#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 [#implementation]

<Steps>
<Step>
### Create a progress component [#create-a-progress-component]

```tsx title="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>
  );
}
```
</Step>

<Step>
### Pass it to the provider [#pass-it-to-the-provider]

```tsx title="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 }}`.
</Step>
</Steps>

Ask the agent for a sales dashboard. Your loader shows while the surface builds, then the dashboard replaces it.

## Action Handlers [#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 [#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](/generative-ui/a2ui/fixed-schema#action-handlers-reference) shows this button in a full schema.

```json
{
  "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:

```typescript
{
  name: "book_flight",
  surfaceId: "flight-search-results",
  sourceComponentId: "book-button",
  timestamp: "2025-01-01T00:00:00.000Z",
  context: { flightNumber: "AA100", price: "$350" },
}
```

### `onAction` interceptor [#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:

```tsx
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.

```tsx
<CopilotKit
  runtimeUrl="/api/copilotkit"
  a2ui={{ catalog: myCatalog }}
  renderActivityMessages={activityRenderers}
>
  {/* ... */}
</CopilotKit>
```

### Forward a modified action [#forward-a-modified-action]

An interceptor can return a modified exported `A2UIUserAction`; the renderer forwards that action to the agent:

```tsx
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 [#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 [#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` |
