A2UI
Use a2ui to turn structured instructions generated by an AI agent into a visible interface. It is useful when the agent decides the UI at runtime, such as generating a result card, list, or chart for a user's request.
If the interface structure is fixed, regular components such as view and text are simpler.
Display an Initial Interface
Give the component a unique id, then pass A2UI instructions through commands. The component processes commands only once, during its initial render.
<a2ui id="answer" commands="{{initialCommands}}"></a2ui>
export default {
data: {
initialCommands: JSON.stringify([
{
version: 'v0.9',
createSurface: { surfaceId: 'main' }
},
{
version: 'v0.9',
updateComponents: {
surfaceId: 'main',
components: [
{ id: 'title', component: 'Text', text: 'Today: sunny' }
]
}
}
])
}
};
commands accepts a string, so use JSON.stringify() to convert the command array to JSON text.
Update the Displayed Interface
When a new AI result arrives, create a context using the component's id, then call write():
const context = a2ui.createA2UIContext('answer');
if (context) {
context.write(JSON.stringify([
{
version: 'v0.9',
updateComponents: {
surfaceId: 'main',
components: [
{ id: 'title', component: 'Text', text: 'Today: cloudy' }
]
}
}
]));
}
createA2UIContext() returns null when the id cannot be found, so check the result before using it.
Receive AI Output in Chunks
If the AI response arrives progressively, create a writer and pass each string chunk to it. Always call close() at the end so the component can finish processing the remaining content.
const context = a2ui.createA2UIContext('answer');
if (context) {
const writer = context.startStream();
writer.writeChunk('{"version":"v0.9","createSurface":');
writer.writeChunk('{"surfaceId":"stream-result"}}');
writer.close();
}
Call context.clear() when the generated interface should be removed.
Properties
| Property | Type | Default | Description |
|---|---|---|---|
id | String | - | Component identifier used by a2ui.createA2UIContext(). Required for dynamic updates. |
commands | String | - | A2UI JSON instructions processed once during the initial render. |
default-chart-animate | Boolean | true | Whether charts created by A2UI animate by default when the instruction does not specify animation. defaultChartAnimate is also accepted. |
JavaScript Methods
| Method | Description |
|---|---|
a2ui.createA2UIContext(id) | Returns the context for a component id, or null when it cannot be found. |
context.write(data) | Updates the interface using a complete JSON string. |
context.startStream() | Starts a chunked update and returns a writer. |
writer.writeChunk(chunk) | Writes one string chunk. |
writer.close() | Finishes the current chunked update. |
context.clear() | Clears the generated interface. |
a2ui does not provide agent-id, session-id, or bindmessage. Manage the agent session and incoming messages in the page or an Agent Worker, then pass the resulting A2UI instructions to this component.
Tint and Fit Generated Images
A2UI Image / image props map to the native Image attributes below:
| A2UI prop | Native attribute | Behavior |
|---|---|---|
tintColor | tint-color | Color string or data binding; explicit tint-color wins when both spellings occur. |
fit: 'contain' | mode="aspectFit" | Shows the entire image at its original aspect ratio. |
fit: 'cover' | mode="aspectFill" | Fills the region, cropping as needed. |
fit: 'fill' | mode="scaleToFill" | Stretches to fill the region. |
mode | mode | Explicit mode takes precedence over fit. |
See Image for alpha multiplication and SVG theme tint. Updates preserve same-type image components and reuse template items by position, avoiding unnecessary image reloads and preserving playback. Changing the component type recreates it.