@a2ui-adaptive/react

A2UI runtime for React: a streaming client, message validator, JSON-pointer data binding, and the full AppCatalog domain components (weather, news, shopping, movies, travel, finance, invoices and more), wrapped in a ready-to-use canvas.

The backend is a separate service. Point this package at it with setBackendBaseUrl and stream intents over SSE.

Install

npm install @a2ui-adaptive/react react react-dom zustand

react >= 18, react-dom >= 18, and zustand ^5 are peer dependencies. Everything else is bundled.

Quick start

import { A2uiCanvas, streamIntent, setBackendBaseUrl } from "@a2ui-adaptive/react";
import "@a2ui-adaptive/react/styles.css"; // required once

setBackendBaseUrl("http://localhost:8000"); // default; points at the A2UI backend

function App() {
  return <A2uiCanvas />;
}

// On submit:
const result = await streamIntent("Show popular movies", { /* userContext */ });
if (result.error) console.error(result.error);

streamIntent POSTs to {backendUrl}/api/stream, streams the A2UI messages into the store via applyMessage, and the canvas re-renders automatically.

API

Canvas

• A2uiCanvas({ surfaceId?, className? }) — renders the most recent surface (or a specific one by id) using A2UIRenderer plus AppCatalog.
• A2UIRenderer — lower-level renderer component; used internally by A2uiCanvas.

Streaming

• streamIntent(text, userContext, history?) → { domain, surfaceId, error, routing } — streams an intent to the backend. history is { role, content, state? }[] for multi-turn conversations.
• setBackendBaseUrl(url) / getBackendBaseUrl() / backendUrl(path) — configure the backend origin.

Actions & validation

• dispatchAction(comp, surfaceId, data, index?) — runs a component's action: local functionCalls (changeTab, toggleCompare, clearCompare) are executed in-app; events are POSTed to {backendUrl}/api/handle-action.
• validateMessage(msg) / CatalogError — validate an A2UI message against COMPONENT_NAMES/LOCAL_FUNCTIONS before applying.

Data binding

• getPointer(data, path) / setPointer(data, path, value) / parsePointer(path) — JSON-pointer helpers used for component bindings.
• JsonPointerError — thrown on malformed pointers.

State & catalog

• useA2UIStore — zustand store. useA2UIStore.getState().applyMessage(msg) applies raw A2UI messages; beginTurn(), patchData(surfaceId, path, value) are also available.
• AppCatalog — Record<componentName, { component }>; extend or replace it to add custom components.
• CATALOG_ID, COMPONENT_NAMES, LOCAL_FUNCTIONS — catalog metadata used by validation.

Types

• A2UIMessage, CreateSurface, UpdateComponents, UpdateDataModel, SurfaceState, Bound, StreamResult, RoutingState.

Custom components

AppCatalog maps A2UI component names to React components. It is a plain exported object, so register your own components directly:

import { AppCatalog } from "@a2ui-adaptive/react";

function MyWidget(props: Record<string, unknown>) {
  return <div>MyWidget</div>;
}

AppCatalog.MyWidget = { component: MyWidget };

Update the backend's catalog (e.g. backend/app/a2ui/catalogs/AppCatalog.json) and COMPONENT_NAMES so the agent knows the component exists and validation accepts it.

Styles

The package ships compiled Tailwind CSS as dist/styles.css. Import @a2ui-adaptive/react/styles.css once in your app entry. If you use a different styling system, the components still work; only the Tailwind utility classes are missing.

Development

npm run build      # vite lib build → dist/{a2ui-react.js, a2ui-react.umd.cjs, styles.css, index.d.ts}
npm run typecheck  # tsc --noEmit