A2UI Renderer
Declarative UI Surface renderer that converts JSON payloads from AI agents into live, interactive interfaces. Supports a whitelisted component catalog, data binding, sandboxed execution, and real-time surface updates.
Preview
A contact form surface generated by an AI agent
Contact Form
Surface ID: contact-form-001v1.0
Rendered Surface
Get in Touch
Fill out the form below and our team will get back to you within 24 hours.
{
"user": {
"name": "",
"email": ""
},
"submitted": false
}Content
Input
Data Viz
Media
Layout
Dashboard Surface
KPI dashboard with charts, progress bars, and data grid
Sales Dashboard
Surface ID: metrics-dash-042v2.1
Rendered Surface
Monthly Performance
Key metrics for the last 30 days.
Revenue
$124,500
Orders
342
Conversion Rate
3.8%
Revenue by Channel
{
"metrics": {
"revenue": 124500,
"orders": 342,
"conversion": 3.8
},
"period": "last_30_days"
}Content
Input
Data Viz
Media
Layout
Data Visualization Surface
Table-based report with filters and chart
User Activity Report
Surface ID: data-table-007v1.2
Rendered Surface
User Activity Report
Overview of user engagement across the platform.
| Name | Role | Activity | Status |
|---|---|---|---|
| Alice Chen | Admin | 142 actions | Active |
| Bob Kumar | Editor | 89 actions | Active |
| Carol Diaz | Viewer | 23 actions | Inactive |
| Dan Park | Editor | 67 actions | Active |
| Eve Morris | Admin | 201 actions | Active |
Actions by Role
{
"filter": "all",
"sortBy": "activity"
}Props
A2UIRenderer component API reference
| Prop | Type | Default | Description |
|---|---|---|---|
surface | SurfaceDefinition | — | The JSON surface definition containing components, data model, and metadata |
messages | A2UIMessage[] | [] | History of agent messages (createSurface, updateComponents, updateDataModel, deleteSurface) |
showCatalog | boolean | true | Show the component catalog panel in the sidebar |
showRawToggle | boolean | true | Show the Raw JSON / Preview toggle button |
showSecurityStatus | boolean | true | Show the security status bar (sandboxed, catalog-restricted) |
showMessageLog | boolean | true | Show the agent message log panel |
onSurfaceUpdate | (surface: SurfaceDefinition) => void | — | Callback when the surface definition is updated |
onAction | (componentId: string, action: string, value?: unknown) => void | — | Callback when a rendered component triggers an action (button click, input change) |
className | string | — | Additional CSS classes for the root container |
SurfaceDefinition
surfaceId: string
title?: string
components: SurfaceComponent[]
dataModel?: Record<string, unknown>
meta?: { version, createdBy, sandboxed, catalogRestricted }
ComponentType (whitelisted)
TextHeadingButtonInputCheckboxSliderSelectBarChartTableImageCardStackGridDividerBadgeProgressA2UIMessageType
"createSurface" |"updateComponents" |"updateDataModel" |"deleteSurface"
Data Binding Types
DynamicString |DynamicNumber |DynamicBoolean— use { $bind: "path.to.value", fallback: ... }
Usage
Import and implementation example
import { A2UIRenderer } from '@/blocks/agentic/a2ui-renderer'import type { SurfaceDefinition } from '@/blocks/agentic/a2ui-renderer'
const surface: SurfaceDefinition = { surfaceId: 'my-surface-001', title: 'My Agent Surface', meta: { version: '1.0', createdBy: 'MyAgent', sandboxed: true, catalogRestricted: true, }, dataModel: { user: { name: 'Alice' }, }, components: [ { id: 'greeting', type: 'Heading', props: { text: 'Hello!', level: 2 }, }, { id: 'name-display', type: 'Text', props: { text: { $bind: 'user.name', fallback: 'Guest' }, }, }, { id: 'action-btn', type: 'Button', props: { label: 'Continue', variant: 'primary' }, }, ],}
export default function Example() { return ( <A2UIRenderer surface={surface} onAction={(id, action, value) => { console.log('Component action:', id, action, value) }} /> )}Built With
3 componentsThis block uses the following UI components from the design system:
Features
Built-in functionality
- JSON-driven rendering: Converts declarative JSON surface definitions into live, interactive React components
- 16 whitelisted component types: Text, Heading, Button, Input, Checkbox, Slider, Select, BarChart, Table, Image, Card, Stack, Grid, Divider, Badge, Progress
- Data binding: DynamicString, DynamicNumber, DynamicBoolean types with $bind path resolution and fallback values
- Agent message support: createSurface, updateComponents, updateDataModel, and deleteSurface message types
- Security status bar: Visual indicators for sandboxed execution and catalog-restricted rendering
- Component catalog panel: Browsable catalog of all supported component types organized by category
- Component tree inspector: Interactive tree view showing the hierarchy of rendered components
- Raw JSON toggle: Switch between rendered preview and the raw JSON payload
- Data model viewer: Inspect the current data model used for data binding resolution
- Message log: Timeline of agent messages showing surface creation and updates
- Nested components: Card, Stack, and Grid components support nested children for complex layouts
- Action callbacks: onAction callback for button clicks, input changes, checkbox toggles, and slider updates
- Dark mode: Full dark mode support across all rendered components and panels
- forwardRef support: Forwards ref to the root container for imperative access
Accessibility
Accessibility considerations
ARIA Attributes
Rendered inputs include associated labels via <label> elementsSecurity status uses semantic color + icon + text for status communicationInteractive elements (buttons, inputs, selects) use native HTML elementsKeyboard Navigation
| Key | Action |
|---|---|
| Tab | Navigate between interactive rendered components and panel controls |
| Enter / Space | Activate buttons, toggles, and expandable panels |
| Arrow Keys | Adjust slider values and navigate select options |
Notes
- All rendered inputs use native HTML elements for built-in accessibility
- Consider adding aria-live region for dynamic surface updates
- Component tree uses click handlers; consider adding keyboard navigation
- Raw JSON view uses <pre> with monospace font for readability
- Security badges communicate status via both color and text