A2UI Component Reference: Basic Catalog Properties

A2UI components are declared as flat objects in an adjacency list rather than a nested JSON tree. Each component carries a unique id, a component type string (v0.9) or wrapper object (v0.8), and its properties at the top level. Parent components reference their children by ID, so any component can be updated independently without touching the rest of the tree. The components documented here are part of the Basic Catalog — a general-purpose catalog maintained by the A2UI team at:

https://a2ui.org/specification/v0_9_1/catalogs/basic/catalog.json

All components share three universal properties: id (required, unique within the surface), accessibility (optional, for label and role hints), and weight (optional, flex-grow value when inside a Row or Column).

Version Differences at a Glance

The component catalogue is largely the same across v0.8 and v0.9. The structural differences are:

Aspect	v0.8	v0.9
Component type declaration	`"component": { "Text": { ... } }`	`"component": "Text", ...props`
String literals	`{ "literalString": "Hello" }`	`"Hello"`
Static children	`{ "explicitList": ["a", "b"] }`	`["a", "b"]`
Dynamic children	`{ "template": { "dataBinding": "/items", "componentId": "tpl" } }`	`{ "path": "/items", "componentId": "tpl" }`
Data binding	`{ "path": "/data" }`	`{ "path": "/data" }` (same)
Text/image styling	`usageHint`	`variant`
Button styling	`primary: true`	`variant: "primary"`
Action format	`{ "name": "..." }`	`{ "event": { "name": "..." } }`
Choice component	`MultipleChoice` (`selections` binding)	`ChoicePicker` (`value` binding)
Layout alignment	`distribution`, `alignment`	`justify`, `align`
TextField value prop	`text`	`value`

Layout Components

Layout components arrange their children visually. Children are always referenced by ID — never nested inline.

Row — horizontal layout container

Arranges child components left-to-right in a horizontal line.

v0.9
v0.8

Properties

children

array | object

Static: array of child IDs. Dynamic: { "path": "/items", "componentId": "template-id" }.

justify

string

Main-axis alignment. Values: start, center, end, spaceBetween, spaceAround.

align

string

Cross-axis alignment. Values: start, center, end, stretch.

{
  "id": "toolbar",
  "component": "Row",
  "children": ["btn-cancel", "btn-ok"],
  "justify": "spaceBetween",
  "align": "center"
}

Properties: children (explicitList or template), distribution, alignment

{
  "id": "toolbar",
  "component": {
    "Row": {
      "children": { "explicitList": ["btn-cancel", "btn-ok"] },
      "distribution": "spaceBetween",
      "alignment": "center"
    }
  }
}

Column — vertical layout container

Arranges child components top-to-bottom in a vertical stack.

v0.9
v0.8

Properties

children

array | object

Static: array of child IDs. Dynamic: { "path": "/items", "componentId": "template-id" }.

justify

string

Main-axis alignment. Values: start, center, end, spaceBetween, spaceAround.

align

string

Cross-axis alignment. Values: start, center, end, stretch.

{
  "id": "content",
  "component": "Column",
  "children": ["header", "body", "footer"],
  "justify": "start",
  "align": "stretch"
}

{
  "id": "content",
  "component": {
    "Column": {
      "children": { "explicitList": ["header", "body", "footer"] },
      "distribution": "start",
      "alignment": "stretch"
    }
  }
}

Display Components

Display components render content but do not accept user input.

Text — text display with variant styling

Renders a string with optional typographic styling.

v0.9
v0.8

text

string | DataBinding

required

The text content. Use a plain string for a literal value, or { "path": "/pointer" } to bind to the data model.

variant

string

Typographic hint. Values: h1, h2, h3, h4, h5, caption, body.

{
  "id": "page-title",
  "component": "Text",
  "text": "Flight Status",
  "variant": "h1"
}

Data-bound example:

{
  "id": "status-label",
  "component": "Text",
  "text": { "path": "/order/status" },
  "variant": "body"
}

Uses usageHint instead of variant. String literals must be wrapped in { "literalString": "..." }.

{
  "id": "page-title",
  "component": {
    "Text": {
      "text": { "literalString": "Flight Status" },
      "usageHint": "h1"
    }
  }
}

Image — URL-based image display

Renders an image from a URL with optional fit and display variant.

v0.9
v0.8

url

string | DataBinding

required

Image URL, or a data binding to a path that holds the URL string.

fit

string

Sizing behavior. Values: contain, cover, fill, none.

variant

string

Display hint (e.g., hero, thumbnail, avatar).

{
  "id": "hero-image",
  "component": "Image",
  "url": "https://example.com/hero.png",
  "fit": "cover",
  "variant": "hero"
}

Uses usageHint instead of variant.

{
  "id": "hero-image",
  "component": {
    "Image": {
      "url": { "literalString": "https://example.com/hero.png" },
      "fit": "cover",
      "usageHint": "hero"
    }
  }
}

Divider — visual separator

Renders a horizontal or vertical separator line between sections.

v0.9
v0.8

axis

string

Orientation of the divider. Values: horizontal (default), vertical.

{
  "id": "section-divider",
  "component": "Divider",
  "axis": "horizontal"
}

{
  "id": "section-divider",
  "component": {
    "Divider": {
      "axis": "horizontal"
    }
  }
}

Card — elevated container

A container with surface elevation, a border, and built-in padding. Holds exactly one child component.

v0.9
v0.8

child

string

required

ID of the single child component to render inside the card.

{
  "id": "info-card",
  "component": "Card",
  "child": "card-content"
}

{
  "id": "info-card",
  "component": {
    "Card": {
      "child": "card-content"
    }
  }
}

Input Components

Input components are bidirectionally bound to the data model. When the user changes a value, the client automatically writes the new value to the bound path.

Button — action trigger

A tappable button that fires an action event when pressed.

v0.9
v0.8

child

string

required

ID of the child component used as the button label (typically a Text).

variant

string

Visual style. Values: primary, secondary, destructive, ghost.

action

object

Action descriptor: { "event": { "name": "event-name" } }.

{
  "id": "submit-btn",
  "component": "Button",
  "child": "submit-label",
  "variant": "primary",
  "action": {
    "event": { "name": "submit_form" }
  }
}

Uses primary: true/false instead of variant. Action format is { "name": "..." }.

{
  "id": "submit-btn",
  "component": {
    "Button": {
      "child": "submit-label",
      "primary": true,
      "action": { "name": "submit_form" }
    }
  }
}

TextField — text input

A single- or multi-line text input. Bidirectionally bound: user edits propagate to the data model automatically.

v0.9
v0.8

label

string

Input label shown above or inside the field.

value

string | DataBinding

Current value. Bind to a data model path to make it reactive.

textFieldType

string

Input type hint. Values: shortText (default), longText, number, obscured, date.

validationRegexp

string

Optional regular expression for client-side validation.

{
  "id": "email-input",
  "component": "TextField",
  "label": "Email Address",
  "value": { "path": "/user/email" },
  "textFieldType": "shortText"
}

Uses text (not value) for the bound property.

{
  "id": "email-input",
  "component": {
    "TextField": {
      "label": { "literalString": "Email Address" },
      "text": { "path": "/user/email" },
      "textFieldType": "shortText"
    }
  }
}

Checkbox — boolean toggle

A labeled checkbox for boolean values. The bound path is automatically set to true or false as the user toggles.

v0.9
v0.8

label

string

Text label displayed next to the checkbox.

value

DataBinding

JSON Pointer path to the boolean value in the data model.

{
  "id": "terms-check",
  "component": "CheckBox",
  "label": "I agree to the terms and conditions",
  "value": { "path": "/form/agreedToTerms" }
}

{
  "id": "terms-check",
  "component": {
    "CheckBox": {
      "label": { "literalString": "I agree to the terms and conditions" },
      "value": { "path": "/form/agreedToTerms" }
    }
  }
}

Slider — numeric range input

A draggable slider for selecting a number within a bounded range.

v0.9
v0.8

value

DataBinding

required

JSON Pointer path to the current numeric value.

minValue

number

required

Minimum allowed value.

maxValue

number

required

Maximum allowed value.

{
  "id": "volume-slider",
  "component": "Slider",
  "value": { "path": "/settings/volume" },
  "minValue": 0,
  "maxValue": 100
}

{
  "id": "volume-slider",
  "component": {
    "Slider": {
      "value": { "path": "/settings/volume" },
      "minValue": 0,
      "maxValue": 100
    }
  }
}

DateTimeInput — date and time picker

A platform-native date and/or time picker.

v0.9
v0.8

value

DataBinding

required

Path to the ISO 8601 date-time string in the data model.

enableDate

boolean

Show the date picker. Defaults to true.

enableTime

boolean

Show the time picker. Defaults to false.

{
  "id": "departure-picker",
  "component": "DateTimeInput",
  "value": { "path": "/booking/departureDate" },
  "enableDate": true,
  "enableTime": true
}

{
  "id": "departure-picker",
  "component": {
    "DateTimeInput": {
      "value": { "path": "/booking/departureDate" },
      "enableDate": true,
      "enableTime": true
    }
  }
}

ChoicePicker / MultipleChoice — select from options

Renders a list of labeled options. The user can select one or more; the selection is written to the bound data model path.

v0.9 — ChoicePicker
v0.8 — MultipleChoice

options

array

required

Array of { "label": string, "value": string } objects.

value

DataBinding

required

Path to the string array of currently selected values in the data model.

variant

string

Selection behavior. Values: mutuallyExclusive (default, single-select), multipleSelection (multi-select).

{
  "id": "country-picker",
  "component": "ChoicePicker",
  "options": [
    { "label": "United States", "value": "us" },
    { "label": "Canada",        "value": "ca" },
    { "label": "Mexico",        "value": "mx" }
  ],
  "value": { "path": "/form/country" },
  "variant": "mutuallyExclusive"
}

In v0.8, option labels use the literalString wrapper and the binding property is selections.

{
  "id": "country-picker",
  "component": {
    "MultipleChoice": {
      "options": [
        { "label": { "literalString": "United States" }, "value": "us" },
        { "label": { "literalString": "Canada" },        "value": "ca" }
      ],
      "selections": { "path": "/form/country" },
      "maxAllowedSelections": 1
    }
  }
}

List Component

List — scrollable list with template support

A scrollable container that supports both a static list of children and a template-based dynamic list driven by an array in the data model.

v0.9
v0.8

children

array | object

Static: array of child IDs. Dynamic: { "path": "/array-path", "componentId": "template-id" }. When dynamic, one instance of template-id is rendered per item in the array, with paths scoped to that item.

direction

string

Scroll axis. Values: vertical (default), horizontal.

align

string

Cross-axis alignment. Values: start, center, end, stretch.

Dynamic list example:

{
  "id": "message-list",
  "component": "List",
  "children": {
    "path": "/messages",
    "componentId": "message-item"
  },
  "direction": "vertical"
}

The template component uses scoped paths. Inside message-item, { "path": "/text" } resolves to /messages/0/text, /messages/1/text, etc.:

{
  "id": "message-item",
  "component": "Card",
  "child": "message-body"
}

{
  "id": "message-body",
  "component": "Text",
  "text": { "path": "/text" }
}

Dynamic lists use the template key inside children:

{
  "id": "message-list",
  "component": {
    "List": {
      "children": {
        "template": {
          "dataBinding": "/messages",
          "componentId": "message-item"
        }
      },
      "direction": "vertical"
    }
  }
}

Container Components

Modal — overlay dialog

An overlay dialog consisting of an entry-point trigger component (e.g., a button) and a content component rendered inside the modal layer.

v0.9
v0.8

entryPointChild

string

required

ID of the component that opens the modal (rendered in the normal flow).

contentChild

string

required

ID of the component rendered inside the modal overlay.

{
  "id": "confirm-modal",
  "component": "Modal",
  "entryPointChild": "open-modal-btn",
  "contentChild": "modal-body"
}

{
  "id": "confirm-modal",
  "component": {
    "Modal": {
      "entryPointChild": "open-modal-btn",
      "contentChild": "modal-body"
    }
  }
}

Tabs — tabbed panel interface

Organizes content into labeled tabs. Each tab item has a title and points to a child component panel.

v0.9
v0.8

tabItems

array

required

Array of { "title": string, "child": string } objects. child is the ID of the panel component to render for that tab.

{
  "id": "settings-tabs",
  "component": "Tabs",
  "tabItems": [
    { "title": "General", "child": "general-panel" },
    { "title": "Privacy", "child": "privacy-panel" }
  ]
}

{
  "id": "settings-tabs",
  "component": {
    "Tabs": {
      "tabItems": [
        { "title": { "literalString": "General" }, "child": "general-panel" },
        { "title": { "literalString": "Privacy" }, "child": "privacy-panel" }
      ]
    }
  }
}

Message Reference

updateComponents, updateDataModel, and all other message types.

Data Binding

How JSON Pointer paths connect component props to live data.

Catalogs

Define your own component catalog or extend the basic catalog.

Transports

Deliver A2UI messages over A2A, AG-UI, WebSockets, and more.

Protocol

Specification

A2UI Component Reference: Basic Catalog Properties

Version Differences at a Glance

Layout Components

Display Components

Input Components

List Component

Container Components

Message Reference

Data Binding

Catalogs

Transports

Build docs developers (and LLMs) love

Protocol

Specification

Documentation Index

​Version Differences at a Glance

​Layout Components

​Display Components

​Input Components

​List Component

​Container Components

Message Reference

Data Binding

Catalogs

Transports

Build docs developers (and LLMs) love

Version Differences at a Glance

Layout Components

Display Components

Input Components

List Component

Container Components