A2UI
Configure typed A2UI catalogs, Angular-owned styles, and incomplete-stream recovery.
When your agent builds UI on the fly, you want it to use only components you approve. A2UI renders the agent's UI in Angular chat from a catalog that you define. The renderer creates only components that the catalog defines.
Choose a schema strategy
Catalog component definitions use Zod schemas for their props. A broad catalog lets the agent compose several application primitives. A fixed catalog narrows the generated interface to a specific domain and set of shapes.
The flight example keeps its component vocabulary deliberately small:
export const fixedDefinitions = {
Card: { props: z.object({ child: z.string() }) },
Title: { props: z.object({ text: dynamicString }) },
Airport: { props: z.object({ code: dynamicString }) },
Arrow: { props: z.object({}) },
AirlineBadge: { props: z.object({ name: dynamicString }) },
PriceTag: { props: z.object({ amount: dynamicString }) },
Button: {
props: z.object({
child: z.string(),
variant: z.enum(["primary", "secondary", "ghost"]).optional(),
action: z.unknown().optional(),
}),
},
} satisfies A2UICatalogDefinitions;Give each catalog a stable catalogId. In an application config, pass the
chosen catalog and lifecycle policy through the a2ui option of
provideCopilotKit:
provideCopilotKit({
runtimeUrl: "/api/copilotkit",
a2ui: {
catalog: productCatalog,
recovery: { showAfterMs: 2_000, showAfterAttempts: 2 },
},
});A catalog is required: without one, A2UI stays off even when the runtime enables it, and CopilotKit logs a warning.
Use existing web components
A catalog entry can also be a Custom Element, such as a component from an
existing design system. Pass { tagName, element } instead of an Angular
component, and mix both kinds freely:
import { ChildListSchema, createAngularCatalog } from "@copilotkit/angular/a2ui";
import { z } from "zod";
const catalog = createAngularCatalog(
{
Badge: { props: z.object({ label: z.string() }) },
Panel: { props: z.object({ children: ChildListSchema }) },
},
{
Badge: { tagName: "acme-badge", element: AcmeBadge },
Panel: PanelComponent,
},
{ includeBasicCatalog: true },
);CopilotKit registers the element, renders it in place of the node, and assigns
the node's A2UI ComponentContext to its context property on every update.
The element reads its props and writes to the data model through that context,
for example with web_core's GenericBinder. Elements render in the browser
only, not during server rendering.
By default, CopilotKit includes the catalog schema in agent context. Set
includeSchema: false only when the server already supplies equivalent schema
and generation instructions. Otherwise the agent cannot reliably know which
components and props are valid. With includeSchema: false, the agent context
lists only the catalog ID and the custom component names. A LangGraph A2UI
subagent then gets only the component names. To give it more, pass a
composition guide through the A2UI guidelines of the CopilotKit middleware.
Style rendered components
Catalog components are Angular components with application-owned class names. Style those classes in the global stylesheet so generated surfaces and their nested elements receive the same rules:
.a2ui-row {
display: flex;
flex-wrap: wrap;
align-items: stretch;
width: 100%;
}
.a2ui-column {
display: flex;
flex-direction: column;
width: 100%;
}
[data-testid="declarative-card"],
.a2ui-chart-card,
.a2ui-flight-card {
display: block;
padding: 1rem;
border: 1px solid var(--line);
border-radius: 0.9rem;
background: light-dark(white, #191a1e);
box-shadow: 0 8px 22px -18px rgb(15 23 42 / 0.4);
}
.a2ui-metric {
display: grid;
min-width: 8rem;
gap: 0.25rem;
}
.a2ui-metric > span,
.a2ui-metric > small {
color: light-dark(var(--muted), #adadb2);
font-size: 0.75rem;
}
.a2ui-metric > strong {
font-size: 1.4rem;
}
.a2ui-status,
.a2ui-airline {
display: inline-flex;
width: fit-content;
padding: 0.25rem 0.55rem;
border-radius: 999px;
background: light-dark(#eef2ff, rgb(30 27 75 / 40%));
font-size: 0.75rem;
font-weight: 700;
}
.a2ui-status-success {
background: light-dark(#dcfce7, rgb(5 46 22 / 40%));
color: light-dark(#166534, #86efac);
}
.a2ui-status-warning {
background: light-dark(#fef3c7, rgb(69 26 3 / 40%));
color: light-dark(#92400e, #fcd34d);
}
.a2ui-status-error {
background: light-dark(#fee2e2, rgb(69 10 10 / 40%));
color: light-dark(#991b1b, #fca5a5);
}Keep semantic state in explicit classes such as a2ui-status-success rather
than asking the model to invent colors. You can also pass an A2UI theme
through provideCopilotKit for renderer-level theme values; catalog CSS
remains the right place for product-specific layout and visual states.
Recover incomplete streams
An interrupted stream can leave an A2UI surface without a terminal lifecycle
event. Configure recovery.showAfterMs to avoid flashing recovery UI during a
normal pause and recovery.showAfterAttempts to wait through transient retry
attempts. The provider sample above uses two seconds and two attempts.
Use recovery.debugExposure only when users should see protocol diagnostics.
Keep it hidden in consumer-facing chat, or choose a collapsed or verbose mode
for internal debugging. Recovery thresholds affect client display; the server
still owns activity lifecycle status and retry behavior.
Angular support boundaries
- Hashbrown is unsupported. The stable Hashbrown Angular package does not support the Angular 22 policy. Use A2UI with a typed catalog instead.
- JSON Renderer is not applicable. JSON Renderer does not provide an Angular renderer; use A2UI for declarative Angular interfaces.
Check the result
Ask the agent to show your data with one of your catalog components. The chat renders that component from your catalog.
Next steps
How is this guide?