Components and surfaces

Let your agent render your own components, in the chat and in areas of your page.

Experimental

Components and surfaces implements A2UI 1.0 as of spec revision cbaa5ee (October 2026). Upstream still calls 1.0 a candidate, and the API of this feature can change. The support matrix lists what is supported. Anything that it does not list is not supported.

What is this?

A text answer is often the wrong answer. "Compare these three plans" wants a table. "Show me cheap running shoes" wants product cards, and maybe in the product row of your page, not in the chat.

With components and surfaces, the agent renders real React, Angular, React Native or Vue components while it answers:

  • In the chat, inside its reply.
  • In areas of your page, outside the chat. Asking the chat changes the page.

You decide what the agent can render. The agent decides what to show and fills in the values. Users can type into the UI, press its buttons, and ask follow-up questions about it.

Try it

These steps add generative UI to a Next.js, Angular, React Native or Vue app, with an OpenAI model through TanStack AI.

Already have CopilotKit running? Do step 3 only. Your runtime needs no change: when the provider sends a catalog with at least one component, the runtime gives that run a render_ui tool and a short guide. Your agent must pass the run's tools and context to its model, as in step 2. For a LangGraph Python agent, add CopilotKitMiddleware.

Install the packages

npm install @copilotkit/react-core @copilotkit/runtime @tanstack/ai @tanstack/ai-openai

Put your OpenAI key in .env.local:

.env.local
OPENAI_API_KEY=sk-...

Add the runtime and an agent

The agent is a built-in agent in factory mode: you call the model yourself with TanStack AI.

app/api/copilotkit/[[...slug]]/route.ts
import { chat } from "@tanstack/ai";
import { openaiText } from "@tanstack/ai-openai";
import {
  BuiltInAgent,
  convertInputToTanStackAI,
  CopilotRuntime,
  createCopilotRuntimeHandler,
  InMemoryAgentRunner,
} from "@copilotkit/runtime/v2";

const agent = new BuiltInAgent({
  type: "tanstack",
  factory: ({ input, abortController }) => {
    const { messages, systemPrompts, tools } = convertInputToTanStackAI(input);
    return chat({
      adapter: openaiText("gpt-6-luna"),
      messages,
      systemPrompts: [
        "You are a helpful assistant. When a visual answer helps, render it with generative UI.",
        ...systemPrompts,
      ],
      tools,
      abortController,
    });
  },
});

const runtime = new CopilotRuntime({
  agents: { default: agent },
  runner: new InMemoryAgentRunner(),
});

const handler = createCopilotRuntimeHandler({ runtime, basePath: "/api/copilotkit" });

export const GET = handler;
export const POST = handler;

Pass on both values from convertInputToTanStackAI:

  • tools has the render_ui tool. Without it, the model cannot render.
  • systemPrompts has the guide: the components, their props, and how to call render_ui. Without it, the model does not know what to render.

Add your own tools and prompts next to them. Do not replace them.

Turn on generative UI

Give the provider the standard catalog. It has 69 ready-made components: layout, text, inputs, tables, charts, maps, and more. On React Native, you give it a catalog of your own native components.

app/providers.tsx
"use client";
import { CopilotKitProvider } from "@copilotkit/react-core/v2";
import { standardUI } from "@copilotkit/react-core/v2/generative-ui";
import "@copilotkit/react-core/v2/styles.css";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <CopilotKitProvider runtimeUrl="/api/copilotkit" generativeUI={{ ui: standardUI }}>
      {children}
    </CopilotKitProvider>
  );
}

The catalog holds React components, so the provider must be created in a client component. Wrap your layout in it, so every page shares one provider. Then put a chat on a page:

app/layout.tsx
import { Providers } from "./providers";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}
app/page.tsx
"use client";
import { CopilotChat } from "@copilotkit/react-core/v2";

export default function Page() {
  return <CopilotChat />;
}

Ask for something visual

Run npm run dev (for Angular, ng serve and npx tsx server.ts; for Vue, also npx tsx server.ts; for React Native, npx tsx server.ts and npx react-native run-ios or run-android), open the page (on React Native, the app), and send:

Compare the Starter, Team, and Enterprise plans in a table

The table fills in while the agent writes it. It is a real component, so a follow-up such as "add a column for support" changes it in place. On React Native, the plans arrive as a PlanList of PlanCards, the components of your catalog.

That is a working setup. The agent now renders standard components in the chat, or, on React Native, your own components in your message list.

See this in Inspector

Open Inspector on localhost. Go to Inspect, then Generative UI. You see the catalog, the targets and surfaces on the page, and the text that each run adds to the prompt of the model.

More detail: Inspector.

When something does not render

The agent answered, but the UI did not show, or it shows the wrong thing. Open Inspector, go to Generative UI, and open the tab for what you see:

What you seeOpenWhat to look for
The pane says "No generative UI"Nothing to openThe provider has no generativeUI config. Pass generativeUI={{ ui }} to CopilotKitProvider, or add provideGenerativeUI({ ui }) to the root providers in Angular. In Vue, bind :generativeUI="{ ui }" in camelCase.
The surface stays empty, or shows its fallbackSurfacesFind the surface and open its card. Rejected operations gives the reason for each dropped operation, for example an unknown component.
A component shows wrong or missing valuesSurfacesThe component tree shows each rendered component with the props that the agent sent.
The agent never uses a component or a functionCatalogSearch for its name. A component that is not in the list is not sent to the model. A function with no mounted handler gets a warning.
You want to see what the model gotPromptThe envelope and the render_ui guide of the last run, and of the next run.

Inspector runs in the browser, so it has no React Native version. On React Native, pass errorBoundary={{ onError }} to GenerativeUIProvider: it reports render failures, invalid props, failed events, failed functions that a component called and operations that the app rejected, with the surface. Operations that the runtime rejected never reach onError. They reach the rejected and error props of the Wrapper (with the ones that the app rejected): the Wrapper of GenerativeUIActivity for a chat surface, and the Wrapper of GenerativeUISurface for a surface in a named area. Both default wrappers show a short error line. The exception is a rejected createSurface. A named area then keeps its fallback and renders no Wrapper; when the app rejected it, onError gets it and <GenerativeUIActivity target="<id>"> shows it. When the runtime rejected it, no activity message is sent for it, so only the model learns of it, in the result of its render_ui call, and nothing on the device shows it. The one exception is a createSurface with the id of a live surface: the runtime adds that rejection to the live surface, whose Wrapper shows it. See Errors on the device.

Learn the ideas

Three ideas carry the whole feature:

  • Surfaces: a place where generated UI renders. The chat is one. Any area of your page can be one.
  • Catalogs: the components that the agent can use, with their props. Use the standard one, or add your own.
  • Transports: how the UI reaches the app. The agent calls a tool, or it writes the UI in its markdown reply.

Build with it

See it in an app

examples/v2/generative-ui-shop is a shop where the chat changes the page. Ask for "top rated" products, and the featured row on the home page swaps to what the agent picked.

How is this guide?