Surfaces
Render generated UI in the chat, or in named areas of your page that the chat can change.
What is this?
The chat is a good place for an answer. It is a bad place for the product grid of your shop. When a user asks "show me cheap running shoes", the shoes belong in the product row of the page, not in a chat bubble.
A surface is one piece of generated UI. Each surface renders in a target, a place where generated UI can go:
- The chat. Always there. The agent can use every component of the catalog. On React Native, you draw chat surfaces yourself, with
GenerativeUIActivity; see Chat surfaces on React Native. The agent is offered the chat target even when the app shows no chat, so a React Native app that renders onlyGenerativeUISurfacetargets, or only the prebuiltCopilotChat(which does not draw surfaces yet), never shows a surface aimed at the chat. - A page target. An area of your page that you mark with
GenerativeUISurface, or<copilot-generative-ui-surface>in Angular. The agent sees it only while it is mounted.
Add a page target
Wrap an area of your page in a target. Give it an id, and tell the agent what the area is for:
import { GenerativeUISurface } from "@copilotkit/react-core/v2/generative-ui";
import { shopUI } from "./catalog";
export function FeaturedProducts({ products }: { products: Product[] }) {
return (
<GenerativeUISurface
id="featured"
ui={shopUI}
description="The Featured Products row of the home page. When the customer asks to see products here, show them as a ProductGrid with one ProductCard for each product. When they ask for the featured products again, delete this surface."
components={["ProductGrid", "ProductCard"]}
fallback={<ProductRow products={products} />}
/>
);
}What each prop does:
id: the target id. The agent names it when it renders here.description: what the area is and what belongs in it. The agent reads it in each run that starts while the target is mounted, so write it like an instruction.fallback: shows until the agent renders here, and again after the agent deletes its surface, unless an older surface of the same target and thread is still live: then that one shows. In Angular, the projected content is the fallback. In Vue, the default slot is the fallback.uiandcomponents: the only components the agent can use here. See Limit the components.
Now "show me cheap running shoes" swaps the row, and "show the featured products again" brings your own row back.
Chat surfaces on React Native
The prebuilt React Native CopilotChat does not draw surfaces yet. Every surface reaches the app as an activity message in agent.messages, though, and GenerativeUIActivity from @copilotkit/react-native/generative-ui draws one wherever you put it:
- In your own message list, one per activity message. Like the web chat,
GenerativeUIActivityshows only surfaces whose target is"chat", so a surface aimed at a page target renders in itsGenerativeUISurfaceand does not show twice. To show a surface of another target, pass that target id in itstargetprop. - On a screen with no chat. A home screen can start a run of its own agent and show the chat surfaces that run renders. This part renders them; the React Native guide has the whole screen, which starts the run once, shows a spinner while it runs and a retry when it fails, and defines
isChatSurface:
import { View } from "react-native";
import { useAgent } from "@copilotkit/react-native/headless";
import { GenerativeUIActivity } from "@copilotkit/react-native/generative-ui";
import { isChatSurface } from "./agentTurns";
export function HomeSurfaces() {
const { agent } = useAgent({ agentId: "home" });
// Every surface that renders here: aimed at the chat, and not deleted. Not only
// the latest activity message, which can be a deleted surface or one aimed at a
// page target, and render nothing.
const surfaces = agent.messages.filter(isChatSurface);
return (
<View>
{surfaces.map((message) => (
<GenerativeUIActivity key={message.id} message={message} agent={agent} />
))}
</View>
);
}GenerativeUIActivity reads the surface from the thread of the agent you pass, so it shows that agent's output even when another agent ran last. It must be under GenerativeUIProvider: without one, or under a provider without ui, it renders nothing, and warns in development.
Limit the components
A product row must hold product cards, not a slider or a chart. components names the only components that the agent can use in this target, the root included:
<GenerativeUISurface id="featured" ui={shopUI} components={["ProductGrid", "ProductCard"]} />- The agent gets the list, so it knows what fits.
- An operation with another component is rejected, and the agent gets the reason.
uitypes the names, so a typo is a type error. Pass the same catalog that you gave the provider.
Leave out components (and ui) to allow every component of the catalog. Names that are not in the catalog are dropped, with a warning in development. An empty list, or one with only unknown names, allows no component: the target is still offered to the agent, but every operation that places a component in it is rejected.
Scroll to the surface
When the agent starts to render into a target, the page scrolls to it, unless it is already on screen. Turn this off for one target:
<GenerativeUISurface id="sidebar-notes" autoScroll={false} />On the web, with a sticky header, give surfaces some room at the top in your CSS:
[data-generative-ui-surface] {
scroll-margin-top: 6rem;
}One target for each item
A target can be specific. A product page can give each product its own target, so its recommendations stay with it when the user moves between products:
<GenerativeUISurface
key={product.id}
id={`recommendations-${product.id}`}
description={`The "You might also like" row under ${product.name}. Show related products here. Never include ${product.name} itself.`}
/>When a component fails
Each component renders inside its own error boundary. One broken component shows a small fallback, and the rest of the surface keeps working. To report errors, or to draw your own fallback:
<CopilotKitProvider
runtimeUrl="/api/copilotkit"
generativeUI={{
ui: shopUI,
errorBoundary: {
onError: (info) => console.warn(info.kind, info.surfaceId, info.error.message),
fallback: ({ retry }) => <button onClick={retry}>Try again</button>,
},
}}
>What the agent knows about surfaces
On every run, the agent gets:
- The targets that are mounted, with their descriptions and component limits, and the chat target.
- The surfaces that already exist, so it can update one in place instead of building a new one.
- The values the user typed into a surface. The agent cannot write over those values.
- The operations that the runtime or the app (the browser, or the React Native app) rejected, with the reason, so the agent can fix them.
To see the same data, open the Surfaces tab of the Generative UI pane in Inspector. If a surface stays empty, see When something does not render.
Next: decide what the agent can render in a surface, with a catalog.
How is this guide?