A2UI Custom Catalog: a Worked Example with 573 Components

A catalog is the contract between an agent and a renderer: the components and functions the agent may use, and the renderer knows how to draw. A2UI ships one, the Basic Catalog of 18 components. A custom catalog adds your own. This page walks through a real one, the A2UI Atomic Catalog, with 573 components, using the files it actually publishes.

6 min read · Updated 15 November 2026

What a custom catalog is

In the words of a2ui.org, a catalog "is a collection of components and functions that acts as a contract between an agent and a renderer." The renderer lists the catalogs it supports (supportedCatalogIds) when a session starts; the agent picks one as the surface default with catalogId in createSurface.

Since v1.0, a surface can also mix catalogs. Any component can name its own catalog with @catalogId, so a surface can take its layout from the Basic Catalog and drop in components from yours. That is how this catalog is meant to be used. One caution about the spelling: Python SDK 0.11.0 accepts catalogId and rejects @catalogId; see the note in the how-to guide.

For a step-by-step build of your own, see How to make an A2UI custom catalog. For what the Basic Catalog already gives you, see A2UI Basic Catalog.

The catalog document

A v1.0 catalog is one JSON Schema document. Its catalogId is an identifier shared by the agent and the renderer; this one is also the address the file is served from. This is the top of the one this site publishes at /catalogue/a2ui-atoms-v1.json, with the component list cut short:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://a2uicatalog.ai/catalogue/a2ui-atoms-v1.json",
  "protocolVersion": "1.0",
  "catalogId": "https://a2uicatalog.ai/catalogue/a2ui-atoms-v1.json",
  "title": "A2UI Atoms Catalog",
  "description": "The A2UI multi-surface atom vocabulary as an A2UI-v1.0 catalog document.",
  "components": {
    "intro": "{ ... }",
    "body": "{ ... }",
    "…": "573 components in all"
  },
  "functions": {}
}

The document also carries instructions: Markdown that an agent SDK adds to the model's system prompt, here telling the model how to compose these components with Basic Catalog containers.

One component definition

Each key under components is a component name; its schema is the field contract. This is stat_card as published, less its two routing keys (x-routing-text, x-intent-phrases):

{
  "stat_card": {
    "type": "object",
    "description": "Glowing neon stat card — large value with label and optional delta",
    "properties": {
      "component": {
        "const": "stat_card"
      },
      "value": {
        "$ref": "common_types.json#/$defs/DynamicString",
        "description": "string"
      },
      "label": {
        "$ref": "common_types.json#/$defs/DynamicString",
        "description": "string"
      },
      "delta": {
        "$ref": "common_types.json#/$defs/DynamicString",
        "description": "string (optional)"
      },
      "is_up": {
        "$ref": "common_types.json#/$defs/DynamicBoolean",
        "description": "bool (optional)"
      },
      "accent": {
        "$ref": "common_types.json#/$defs/DynamicString",
        "description": "string (optional)"
      }
    },
    "required": [
      "component"
    ],
    "x-surfaces": [
      "web",
      "google-meet-stage",
      "google-apps-script-web",
      "mcp-apps",
      "android"
    ],
    "x-renderers": {
      "react": "drawn",
      "lit": "drawn",
      "angular": "drawn",
      "copilotkit": "drawn",
      "a2ui-vue": "drawn",
      "flutter": "native",
      "compose": "native"
    }
  }
}

The fields use the shared types from the A2UI spec (DynamicString, DynamicBoolean), so any of them can be a literal or bound to the data model with {"@path": ...}.

Using it alongside the Basic Catalog

The surface below sets the Basic Catalog as its default and gives the one component from this catalog its own @catalogId. The Column and Text come from the Basic Catalog; stat_card comes from this one. It is the output of the same emitter that serves this site's surfaces, and the repository's tests check it against the official v1.0 schema and against the stat_card definition above, then render it. The v1.0 spec spells the key @catalogId, as here. Python SDK 0.11.0 (15 November 2026) rejects that spelling and accepts catalogId; upstream's main branch accepts both and no release has it yet.

{
  "version": "1.0",
  "createSurface": {
    "surfaceId": "sales",
    "catalogId": "https://a2ui.org/specification/v1_0/catalogs/basic/catalog.json",
    "components": [
      {
        "component": "Text",
        "text": "# Weekly sales",
        "id": "heading_0"
      },
      {
        "id": "stat_card_1",
        "component": "stat_card",
        "value": "1,234",
        "label": "Orders this week",
        "delta": "+12%",
        "is_up": true,
        "@catalogId": "https://a2uicatalog.ai/catalogue/a2ui-atoms-v1.json"
      },
      {
        "id": "root",
        "component": "Column",
        "children": [
          "heading_0",
          "stat_card_1"
        ]
      }
    ],
    "metadata": {
      "extensions": {
        "a2uicatalog_surface": {
          "title": "Weekly sales",
          "catalogs": [
            "https://a2uicatalog.ai/catalogue/a2ui-atoms-v1.json"
          ]
        }
      }
    }
  }
}

metadata.extensions is the spec's extension point for a surface's own data. A renderer has to list this catalog in supportedCatalogIds before an agent may send it these components; for a renderer that supports only the Basic Catalog, the emitter sends a Basic-only version of the surface instead.

Beyond the spec: where each component works

The spec lets a catalog add its own keys. This one adds two to every component:

Measured today, these web renderers draw this many of the 573 components:

Renderer Components it draws
React 517 of 573
Angular 517 of 573
Lit 518 of 573
CopilotKit 482 of 573
a2ui-vue 482 of 573

A design choice: alongside, not a superset

A common way to build a custom catalog is to include the whole Basic Catalog in it, so the custom catalog is a superset. This one does not. It holds only its own components and leaves layout, text and inputs to the Basic Catalog, joined on the surface by @catalogId. The Basic Catalog stays exactly as Google publishes it, renderers load the two catalogs separately, and a surface names which catalog each component comes from.

Get started

Independent, unofficial catalog: not affiliated with, endorsed by, or sponsored by Google or Anthropic. A2UI is Google's protocol; MCP is Anthropic's. Maintained by Curtis Krygier. MIT License.