Bote A2UI

July 21, 2026 · View on GitHub

A React rendering SDK for the A2UI protocol — turn LLM-generated UI messages into interactive web interfaces, with theming, custom components, and a live Playground.

English | 中文 · Repository: github.com/BoteAI/a2ui

This project is under active development. @boteai/a2ui-render, @boteai/a2ui-custom-kit, and @boteai/a2ui-comp-preset are being prepared for open source. Feedback and contributions are welcome.

Try the Playground

Browse 30+ component demos, switch themes, and edit JSON — no Agent setup required.

Requirements: Node.js 16+ and Yarn 1.x

git clone https://github.com/BoteAI/a2ui.git
cd a2ui

yarn bs          # install workspace dependencies
yarn build       # build packages (first run or after package changes)
yarn start       # start Playground dev server

Open in your browser:

Page	URL
Playground v0.9 (default)	http://localhost:8000/#/a2ui-playgroup/v9
Playground v0.8	http://localhost:8000/#/a2ui-playgroup/v8
Preset component catalog	http://localhost:8000/#/a2ui-preset-catalog?component=PresetSelect
Custom component guide	http://localhost:8000/#/a2ui-playgroup/v9/custom-components-guide

Alternatively: cd app && yarn dev — same as yarn start from the repo root.

While developing packages, run yarn watch in another terminal to rebuild @boteai/a2ui-render, @boteai/a2ui-custom-kit, and @boteai/a2ui-comp-preset on change.

What Problem Does It Solve?

When an AI Agent or backend sends A2UI protocol messages (structured JSON describing UI layout, data bindings, and actions), you need a client-side renderer that can:

Parse streaming or batch protocol messages
Draw standard A2UI components (Text, Button, Card, List, …)
Apply consistent theming across surfaces
Wire user interactions back to your business layer via onAction
Extend the component catalog when the protocol references your own component names

Bote A2UI is a Web / React solution for that pipeline, focused on browser-based Agent UI, chat bubbles, admin consoles, and micro-frontends.

Agent / Backend
      │  A2UI messages JSON
      ▼
@boteai/a2ui-render          ← protocol renderer (React + Lit surface)
      │  customComponents registry
      ├──────────────────────────────────┐
      ▼                                  ▼
@boteai/a2ui-comp-preset       @boteai/a2ui-custom-kit
(built-in Preset components)   (define, register, bundle custom components)
      │                                  │
      └──────────────┬───────────────────┘
                     ▼
        Your business UI (local bundle or remote .mjs)

Packages

Package	npm	Role
a2ui-render	`@boteai/a2ui-render`	A2UI v0.8 / v0.9 protocol renderer
a2ui-custom-kit	`@boteai/a2ui-custom-kit`	Custom component authoring toolkit
a2ui-comp-preset	`@boteai/a2ui-comp-preset`	Built-in Preset component registry and JSON Schemas

This repo also ships a Playground app under app/ for browsing demos, editing JSON, and validating custom components — not published to npm.

BaseRenderer accepts an array of A2UI messages and renders a fully interactive surface. Supports protocol v0.8 and v0.9, automatic version inference, responsive helpers, and declarative action callbacks.

import { BaseRenderer, type A2UIMessage } from '@boteai/a2ui-render';

<BaseRenderer
  messages={messages}
  protocolVersion="0.9"
  themePreset="deepBlueWisdom"
  onAction={({ name, context }) => {
    // handle button clicks, form submits, etc.
  }}
/>

2. Built-in Theme Presets — One-Prop Switching

Four curated visual themes ship out of the box (plus a default base), each implemented as CSS variable overrides and optional Shadow DOM stylesheets. Switch themes at runtime with a single themePreset prop — no rebuild required.

Preset	Description
`default`	A2UI Lit default tokens
`conversation`	Chat-friendly spacing and rounded controls
`cyber`	Vibrant tech / neon accent style
`platformInterconnect`	Enterprise platform interconnect look
`deepBlueWisdom`	Deep blue wisdom dashboard style

See packages/a2ui-render/styleVars.md for the full token list.

3. Custom Components — Two Integration Paths

When protocol messages reference your own component names, register implementations via @boteai/a2ui-custom-kit:

Path	When to use	Output
Local registry	Components live in the same app as the renderer	`customComponents` object passed to `BaseRenderer`
Remote ESM bundle	Independent teams, CDN delivery, micro-frontends	esbuild `.mjs` loaded via `loadRemoteA2UICustomRegistry`

Both paths share the same registry shape — define API with Zod, implement as native Web Component or React bridge, merge entries, and hand off to the renderer.

Custom component development and runtime rendering pipeline

Typical local flow

import {
  defineComponentApi,
  createReactComponent,
  defineRegistryEntry,
  mergeRegistryEntries,
} from '@boteai/a2ui-custom-kit';

const api = defineComponentApi({ name: 'MyCard', shape: { title: z.string() } });
const element = createReactComponent(({ title }) => <div>{title}</div>);
const registry = mergeRegistryEntries(defineRegistryEntry({ api, element }));

Remote flow

import { loadRemoteA2UICustomRegistry, mergeRegistryEntries } from '@boteai/a2ui-render';

const remote = await loadRemoteA2UICustomRegistry(
  'https://cdn.example.com/custom-components.mjs',
);
const customComponents = mergeRegistryEntries(localRegistry, remote);

Detailed guides: packages/a2ui-custom-kit/README.md · app/public/docs/custom-components-guide.md

4. A2UI Playground

A built-in Playground lets you explore, preview, and iterate without wiring a full Agent first.

A2UI Playground — component gallery with theme switching

Capability	Details
Component gallery	30+ v0.9 demos across cards, forms, data views, and special scenarios
Protocol toggle	Switch between A2UI v0.8 and v0.9
Live theme switch	Preview all built-in presets side by side
JSON editor	Edit messages in place and see instant preview
Custom component guide	Open Remote Showcase in the gallery → Development Guide, or read `app/public/docs/custom-components-guide.md`

See Try the Playground for how to start the app locally.

5. Built-in Preset Components (`@boteai/a2ui-comp-preset`)

The official A2UI catalog covers core layout and input primitives. @boteai/a2ui-comp-preset ships a curated set of production-ready Preset components — data tables, charts, metrics, dashboard cards, and more — so integrators can use richer UI without building everything from scratch.

A2UI Preset Component Catalog — browse, preview, and edit Messages JSON

The Playground includes a Preset Component Catalog (/a2ui-preset-catalog). Browse all 12 components by category (layout, content, data display, interactive, card), preview live rendering, inspect props, and edit Messages JSON inline.

Page	URL
Preset catalog (example: Select)	http://localhost:8000/#/a2ui-preset-catalog?component=PresetSelect
Preset catalog (index)	http://localhost:8000/#/a2ui-preset-catalog

Full component reference (props, examples, how to add new presets): packages/a2ui-comp-preset/README.md

Component	Description
`PresetTitle`	Section / page title
`PresetButton`	Styled action button
`PresetBadge`	Status / label badge
`PresetSelect`	Dropdown select (antd)
`PresetRow` / `PresetColumn`	Flex layout containers
`PresetMetric`	KPI / metric card
`PresetDashboardCard`	Dashboard summary card
`PresetDataTable`	Data table
`PresetBarChart` / `PresetPieChart`	Charts (recharts)
`PresetFlightCard`	Flight status card (domain example)

Pass the generated registry to BaseRenderer.customComponents:

import { BaseRenderer } from '@boteai/a2ui-render';
import { a2uiPresetComponentRegistry } from '@boteai/a2ui-comp-preset';

<BaseRenderer
  messages={messages}
  protocolVersion="0.9"
  customComponents={a2uiPresetComponentRegistry}
  onAction={handleAction}
/>

Subpath exports for tree-shaking and tooling:

Import path	Export	When to use
`@boteai/a2ui-comp-preset`	registry + schemas	Full bundle
`@boteai/a2ui-comp-preset/registry`	`a2uiPresetComponentRegistry`	Runtime rendering only
`@boteai/a2ui-comp-preset/schemas`	`a2uiPresetComponentSchemas`	Agent prompts, configurators, codegen

To add a new Preset component: create a folder under packages/a2ui-comp-preset/src/, register the name in manifest.ts, then run yarn build. The build script auto-generates registry.ts, per-component JSON Schemas, and embedded Less styles. See packages/a2ui-comp-preset/README.md for the full component list and step-by-step guide.

6. Roadmap — More Preset Components

More Preset components — carousels, rich text, and domain widgets — will land in @boteai/a2ui-comp-preset. Contributions and RFCs are welcome via Issues.

Architecture

┌─────────────────────────────────────────────────────────────┐
│  Agent / LLM                                                 │
│  emits updateComponents / updateDataModel messages           │
└──────────────────────────┬──────────────────────────────────┘
                           │ JSON
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  @boteai/a2ui-render                                           │
│  BaseRenderer → LitSurfaceHost → @a2ui/lit Web Components  │
│  · theme presets · onAction · remote registry merge          │
└──────────────────────────┬──────────────────────────────────┘
                           │ component name lookup
              ┌────────────┴────────────┐
              ▼                         ▼
┌──────────────────────────┐  ┌─────────────────────────────┐
│  @boteai/a2ui-comp-preset │  │  @boteai/a2ui-custom-kit       │
│  PresetDataTable · charts │  │  defineComponentApi · React/   │
│  · metrics · layouts      │  │  native adapters · remote ESM │
└──────────────────────────┘  └─────────────────────────────┘

Which package do I need?

Standard A2UI components only → @boteai/a2ui-render
Built-in Preset components (tables, charts, …) → @boteai/a2ui-comp-preset (+ render)
Custom components in-app → @boteai/a2ui-custom-kit + render; kit produces registry, render consumes it
Custom components as remote scripts → kit for authoring + render's loadRemoteA2UICustomRegistry at runtime

Quick Start

Install

yarn add @boteai/a2ui-render

# built-in Preset components (tables, charts, metrics, …)
yarn add @boteai/a2ui-comp-preset

# if you need custom components
yarn add @boteai/a2ui-custom-kit

Minimal render

import { BaseRenderer } from '@boteai/a2ui-render';

export function AgentPanel({ messages }) {
  return (
    <BaseRenderer
      messages={messages}
      protocolVersion="0.9"
      themePreset="conversation"
      onAction={(event) => console.log(event.name, event.context)}
    />
  );
}

With built-in Preset components

import { BaseRenderer } from '@boteai/a2ui-render';
import { a2uiPresetComponentRegistry } from '@boteai/a2ui-comp-preset';

<BaseRenderer
  messages={messages}
  protocolVersion="0.9"
  customComponents={a2uiPresetComponentRegistry}
  onAction={handleAction}
/>

With custom components

import { BaseRenderer } from '@boteai/a2ui-render';
import { mergeRegistryEntries } from '@boteai/a2ui-custom-kit';
import { a2uiPresetComponentRegistry } from '@boteai/a2ui-comp-preset';
import { myCustomRegistry } from './my-custom-registry';

<BaseRenderer
  messages={messages}
  protocolVersion="0.9"
  customComponents={mergeRegistryEntries(a2uiPresetComponentRegistry, myCustomRegistry)}
  onAction={handleAction}
/>

API Highlights

`@boteai/a2ui-render`

Export	Description
`BaseRenderer`	Core renderer — messages + optional registry
`BoteRenderer`	Bote-specific renderer extension
`LitSurfaceHost`	Low-level Lit surface host (advanced)
`A2UI_THEME_PRESETS` / `A2UI_THEME_PRESET_NAMES`	Built-in theme definitions
`loadRemoteA2UICustomRegistry`	Dynamic import a remote `.mjs` registry
`loadRemoteA2UICustomRegistries`	Batch-load multiple remote registries
`inferProtocolVersionFromMessages`	Auto-detect v0.8 vs v0.9
`useResponsive` / `isMobile`	Responsive utilities

`@boteai/a2ui-custom-kit`

Export	Description
`defineComponentApi`	Zod-based component API schema
`defineRegistryEntry` / `defineSimpleRegistryEntry`	Build registry entries
`mergeRegistryEntries`	Merge local + remote registries
`createReactComponent`	React → A2UI custom element adapter
`createNativeElement`	Native Web Component adapter
`readComponentProps` / `dispatchA2UIAction`	Runtime element helpers
`subscribeV09ComponentUpdates`	Subscribe to v0.9 property updates

`@boteai/a2ui-comp-preset`

Export	Description
`a2uiPresetComponentRegistry`	Built-in Preset component registry — pass to `BaseRenderer.customComponents`
`a2uiPresetComponentSchemas`	Per-component JSON Schemas (agent / codegen format)

Subpath exports: @boteai/a2ui-comp-preset/registry, @boteai/a2ui-comp-preset/schemas.

Development

# install all workspace dependencies
yarn bs

# start Playground (see "Try the Playground" above)
yarn start

# watch all packages
yarn watch

# build all packages
yarn build

# publish (bumps version + gitHead)
yarn pub a2ui-render 0.1.1
yarn pub a2ui-custom-kit 0.1.1
yarn pub a2ui-comp-preset 0.1.0

License

Apache