Catalogs

Declare the components the agent can render, with typed props, in one catalog.

What is this?

The agent cannot render a component it does not know about. It also needs to know the props of each one, or it guesses, and a guessed price or a wrong prop breaks the page.

A catalog lists the components that the agent can use. For each component it holds the component, a description, and a schema of its props. The agent gets the descriptions and the schemas. Your app gets typed props.

Create a catalog

Declare the catalog once, at module level, with createGenerativeUI:

app/catalog.tsx
import { z } from "zod";
import {
  createGenerativeUI,
  type GenerativeUIComponentProps,
} from "@copilotkit/react-core/v2/generative-ui";

function ProductGrid({ title, children }: GenerativeUIComponentProps<typeof shopUI, "ProductGrid">) {
  return (
    <section>
      {title ? <h3>{title}</h3> : null}
      <div className="grid grid-cols-2 gap-4">{children}</div>
    </section>
  );
}

function ProductCard({ name, price, imageUrl }: GenerativeUIComponentProps<typeof shopUI, "ProductCard">) {
  return (
    <article>
      <img src={imageUrl} alt={name} />
      <h4>{name}</h4>
      <p>${price}</p>
    </article>
  );
}

export const shopUI = createGenerativeUI({
  id: "acme/shop@1",
  components: {
    ProductGrid: {
      component: ProductGrid,
      description: "A grid of products. Put the ids of ProductCard components in children.",
      props: z.object({ title: z.string().optional() }),
      slots: { children: "multiple" },
    },
    ProductCard: {
      component: ProductCard,
      description: "One product. Copy every value from a product of a tool result.",
      props: z.object({ name: z.string(), price: z.number(), imageUrl: z.string() }),
    },
  },
});

Then give it to the provider:

<CopilotKitProvider runtimeUrl="/api/copilotkit" generativeUI={{ ui: shopUI }}>

The id names the catalog. Use a versioned id, for example acme/shop@1.

What a component can declare

  • component: the component that renders.
  • description: what the component is and when to use it. The agent reads it, so be specific.
  • props: the schema of the props that the agent sets.
  • slots: props that hold child components. "single" takes one child, and "multiple" takes a list.
  • A child reference inside the props schema: mark a prop with child() or childList() from @copilotkit/react-core/v2/generative-ui (in Angular, from @copilotkit/angular/generative-ui; on React Native, from @copilotkit/react-native/generative-ui; in Vue, from @copilotkit/vue/v2/generative-ui), anywhere in the schema, for example tabs: z.array(z.object({ title: z.string(), child: child() })). The engine renders the referenced components and your component receives them in place of the ids, as React nodes, as Angular GenerativeUIChildren handles, or as Vue VNodes that you render with <component :is>. This is how A2UI 1.0 marks references (ComponentId, ChildList); slots stays for the plain top-level case. child() and childList() return zod 3 schemas, so write a schema that uses them with zod 3: a zod 4 z.object that holds one throws when the catalog module loads ("expected a Zod schema"). With zod ^3.25 installed, import { z } from "zod" is zod 3; with zod 4, import it from "zod/v3". The React Native setup installs zod 3.
  • events, bind, and writable: actions, app state, and inputs. See Connect app state and actions.

Next to id and component, each component that the agent writes can carry the A2UI 1.0 envelope:

  • catalogId: the id of your UI. It must match.
  • metadata: { "extensions": { ... } }, kept for your own tools.
  • accessibility: label, description, live, and hidden. label, description, and hidden can be bindings or function values.

The engine resolves accessibility and keeps all three fields out of your props. hidden and live apply to every component: when the agent sends an accessibility envelope for a component, the engine wraps it in an element with aria-hidden and aria-live. A component sent without an envelope gets no wrapper. A label or a description needs an element with a role, so the standard components set them on their root or on their control.

In your own component, call useGenerativeUIAccessibility() and spread the result on the root element, or bind the result of injectGenerativeUIAccessibility() to the host in Angular. In Vue, put v-bind with the result on the root element. A component that must not be wrapped (a table row or cell) declares accessibility: "self" and applies the attributes itself.

On React Native, the wrapper is a real View that applies hidden and live (a live region is announced on Android only; on iOS, announce a change with AccessibilityInfo.announceForAccessibility). It never applies label or description: on iOS a label on a view that is not an accessibility element names nothing, and making the wrapper one would merge every control inside it. It cannot be made layout-transparent, and it becomes the flex item of the parent: a component sized or aligned against its parent (flex or flexGrow along the parent's main axis, alignSelf across it, or a percentage size) resolves against the wrapper instead, so it no longer fills the parent or lines up in it. That is why the ProductCard above has a fixed width. A component that needs that sizing declares accessibility: "self", which removes the wrapper, and must then apply hidden and live itself: set aria-hidden and aria-live from useGenerativeUIAccessibility() on its root view (React Native 0.71+ reads them), or map them to accessibilityElementsHidden, importantForAccessibility and accessibilityLiveRegion. Spreading the whole result works on 0.71+, but it also passes aria-description, which React Native has no prop for and ignores. With or without the wrapper, a component that needs a name or a hint reads aria-label and aria-description from useGenerativeUIAccessibility() and sets them on a view of its own that is an accessibility element (accessible), for example as accessibilityLabel and accessibilityHint.

Type your components

GenerativeUIComponentProps<typeof ui, "Name"> gives a component the exact props that the renderer passes. It reads them from the schema, so the component and the catalog cannot drift apart:

function ProductCard(props: GenerativeUIComponentProps<typeof shopUI, "ProductCard">) {
  props.price; // number
  props.color; // type error: not a prop of ProductCard
}

Pick a schema library

props takes any Standard Schema of an object. The agent gets the props as JSON Schema, so the schema must be able to give one:

import { z } from "zod";

props: z.object({ name: z.string(), price: z.number() }),

These work: zod 3.25 or later, zod 4.2 or later, ArkType, and Valibot with @valibot/to-json-schema. A schema that holds child() or childList() must be zod 3, as above. The schema must validate synchronously, because props are checked while a surface renders.

Combine catalogs

extends merges other catalogs into yours. The result has the types of every component:

import { createGenerativeUI, standardUI } from "@copilotkit/react-core/v2/generative-ui";

export const appUI = createGenerativeUI({
  id: "acme/app@1",
  extends: [standardUI, cartUI],
  components: { Hero: { component: Hero, props: z.object({ title: z.string() }) } },
});

A name can come from one catalog only. Two components named Card throw an error when the app loads. To replace a standard component, use overrides.

Export the catalog for other A2UI tools

This section and the next are for catalog authors who use the catalog with other A2UI tools or with A2UI Express. To add components to your app, skip to What the agent sees.

exportA2UICatalog(ui) writes your UI as an A2UI 1.0 catalog definition (the catalog_definition.json shape), for a validator, another renderer or a prompt builder:

import { exportA2UICatalog } from "@copilotkit/react-core/v2/generative-ui";

const catalog = exportA2UICatalog(appUI, { title: "Acme app" });
fs.writeFileSync("acme-catalog.json", JSON.stringify(catalog, null, 2));

Each component in the export is an entry with:

  • component as a const.
  • The props that the model sets. A prop takes its literal schema, a DataBinding, or a FunctionCall, because the renderer resolves dynamic values in any prop.
  • Its events as Action references.
  • Its slots as ComponentId or ChildList references.

Every function states returnType and allowedCallers, built-in or declared. The export also lists calc and series. A tool that does not have these two functions can see that it cannot run them.

Who may call a function

A function declaration can carry the A2UI 1.0 interface fields. allowedCallers is "rendererOnly" (event bindings and prop values), "agentOnly" (callRendererFunction) or "rendererOrAgent". requiresUserActivation: true limits a function to a user gesture, like openUrl, which makes it rendererOnly. returnType names what the handler gives back, with the A2UI names ("string", "number", "boolean", "array", "object", "validationResult", "any", "void").

functions: {
  addToCart: { parameters: z.object({ productId: z.string() }), allowedCallers: "rendererOrAgent", returnType: "object" },
  track: { parameters: z.object({ event: z.string() }), returnType: "void" },
  reload: { parameters: z.object({}), allowedCallers: "agentOnly" },
},

If you leave out allowedCallers, only the UI can call the function, as in A2UI 1.0. The manifest and the exported catalog always write the value out, so a 1.0 reader sees the same thing. An event cannot match an "agentOnly" function, and the built-in functions are value functions of the UI.

In this version, the agent cannot call renderer functions, whatever allowedCallers says. The engine rejects a callRendererFunction operation, and the prompt does not mention it. A result goes back to the model as a developer message, and not every backend keeps that message where the model reads it in order. The declaration fields go into the catalog export.

Positional parameter order

A2UI Express maps positional arguments using the order of properties in the catalog's JSON Schema. Its schema-driven key mapping specification defines that behavior. The choice of which parameters come first belongs to the catalog author.

Declare parameterOrder to put a component's main content, children or actions first, across props, slots and events:

const ui = createGenerativeUI({
  id: "acme/panel@1",
  components: {
    Panel: {
      component: Panel,
      props: z.object({ title: z.string(), color: z.string().optional() }),
      slots: { children: "multiple" },
      parameterOrder: ["title", "children"],
    },
  },
});

exportA2UICatalog(ui) emits Panel.properties in the order component, title, children, color. Express ignores the structural component discriminator, so the first positional argument is the title. The export does not contain a parameterOrder key. It writes the properties in that order.

The rules for parameterOrder:

  • Names must be unique declared props, slots, or events.
  • An ordered component cannot declare integer names ("0" through "4294967294"). JavaScript sorts those keys numerically before other keys, whatever the requested order.
  • Unlisted names follow in declaration order: props, then slots, then events.
  • Bound props and matched events are left out of the signature that the model sees.
  • extends, omit, and overrides keep the declared order.

A catalog without parameterOrder keeps its export order.

Treat positional order as an API contract. Changing it can change the meaning of existing Express programs; named arguments keep their meaning. Keep short prefixes stable and use named arguments for optional styling. Preserve property order when serializing or transforming a catalog for Express.

The standard catalog puts content, children, labels, values, and common actions before presentation parameters. For example, its short prefixes are Text(text?, children?), Column(children?), Button(label?, onClick?), TextField(label?, value?), and Chart(data?, xKey?, series?, chartType?). Other component-specific fields follow, then shared layout and typography fields. CopilotKit chose this order. A2UI does not prescribe these signatures.

What the agent sees

The agent gets each component with its description and the props that it can set. It does not see:

  • Props that come from app state (bind).
  • Events that your own code handles.

To see this list, open the Catalog tab of the Generative UI pane in Inspector. It groups the components by the catalog that declared them, so you can see what extends added.

Next: start from the standard catalog, then add your own components on top.

How is this guide?