Components and surfaces

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 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 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, 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.

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

OPENAI_API_KEY=sk-...

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-5.5"),
      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;

"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>
  );
}

import { Providers } from "./providers";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

"use client";
import { CopilotChat } from "@copilotkit/react-core/v2";

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

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

That is a working setup. The agent now renders standard components in the chat.

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:

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 browser. The agent calls a tool, or it writes the UI in its markdown reply.

Build with it#

• Use the standard catalog: what is in it, and how to drop or replace components.
• Connect app state and actions: show live app data, run your code on a click, and keep what users type.
• Theme the components: your colors and fonts, and dark mode.
• Markdown mode: the agent writes the UI inside its reply, with no tool call.
• Adopt from A2UI: move from the a2ui renderer, with the v0.9 to 1.0 mapping and a support matrix.

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.