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:
x-surfaces: where the component works, from web pages to Google Chat, email, PDF and slides.x-renderers: which renderers draw it, measured, with evidence and dates inrenderer-matrix-v1.json.
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
- The catalog document:
/catalogue/a2ui-atoms-v1.json(catalogIdhttps://a2uicatalog.ai/catalogue/a2ui-atoms-v1.json). - Every component with its live preview: the catalog.
- The MCP server agents use to find and render components:
https://a2uicatalog.ai/mcp. - New to the protocol? Start with What is A2UI?.