a2ui-shadcn logoa2ui-shadcn
DocsPlayground

Resources

  • Documentation
  • Playground
  • A2UI Protocol

Community

  • GitHub
  • Issues
  • shadcn/ui

More

  • Tailwind CSS
  • Next.js
  • React

a2ui-shadcn.shahnazar.me

Created by Reza Shahnazar

Getting Started

  • Introduction
  • Installation
  • Usage

Components

  • Components
    Layout
    ColumnRowCard
    Content
    Text
    Input
    TextFieldCheckBox
    Interactive
    Button
    Feedback
    Badge

Reactivity & Actions

  • Actions
  • Transport

Styling

  • Theming
  • RTL Support

Advanced

  • Custom Components
  • API Reference
  1. Home
  2. /Docs
  3. /Actions
IntroductionInstallationUsageComponentsThemingRTL SupportCustom ComponentsActionsTransportAPI Reference

Actions

Handle user interactions with A2UI action messages, including button clicks, form submissions, and reactive data binding.

Handling Actions

Process user interactions with action handlers.

Actions & Reactive Behavior

a2ui-shadcn provides two reactive flows: two-way data binding for inputs and event actions for buttons and links.

How a2ui-shadcn Handles Reactivity & Actions

Two reactive flows: instant local updates (inputs) and agent-bound actions (buttons)

Two-Way Binding (Inputs)

1
User types/checks
TextField, CheckBox, Slider
2
dataModel.set(path, value)
Immediate local update (no server)
3
Store notifies subscribers
Zustand subscription
4
Bound components re-render
Text, display components update

User Actions (Buttons, Links)

1
User clicks
Button/Link with action.event
2
Resolve context recursively
{ path } -> values, { call } -> exec
3
Build action payload
name, context, sourceComponentId
4
Add dataModel (if sendDataModel)
Full state snapshot included
5
onAction + transport
To parent callback / WebSocket / SSE
Key Concepts:
  • Path bindings: { path: "/key" } - resolved to current data model value
  • FunctionCall: { call: "formatDate", args: {...} } - executed and result included in context
  • sendDataModel: When enabled in createSurface, full data model sent with every action
Try It Yourself

These are live, interactive examples. Type in the inputs and click buttons to see how a2ui-shadcn handles reactivity and actions.

Two-Way Data Binding

As you type, the data model updates immediately and the Text component below re-renders with the new value (no server round-trip).

Action with Context Resolution

Fill the form and click Submit. The button's context (with path bindings) is resolved to current values and sent via onAction.

Two-Way Binding: Input components (TextField, CheckBox, Switch, Slider, ChoicePicker) use value or checked with { "path": "/key" }. When the user types or toggles, dataModel.set(path, value) runs immediately. The store notifies subscribers, and any component bound to that path (e.g. Text with text: { "path": "/key" }) re-renders with the new value. No server round-trip is needed for live updates.

User Actions: Buttons and links with action: { event: { name, context } } resolve context path bindings to current values at click time, then call onAction with the resolved data. When using transports (WebSocket, SSE), actions are sent to the agent. The agent can respond with updateDataModel or updateComponents to update the UI.

Action Structure

typescript

Basic Handler

tsx

Form Actions

json

Handler:

tsx

Context Resolution

When a button is clicked, all context values are resolved before calling onAction. Resolution happens recursively:

Path Bindings: { "path": "/user/email" } - current value from data model

Nested Objects: Entire object structure is resolved recursively

FunctionCall: { "call": "formatDate", "args": {...} } - function executed, return value used

json

Resolved context sent to onAction:

json

sendDataModel

Enable sendDataModel: true in createSurface to automatically include the full data model with every action:

json

Action payload will include dataModel:

typescript

This is useful when the agent needs the full UI state alongside the user's action.

Context Functions

Register functions that return values for use in action context:

tsx

Agent uses in button context:

json

Client-Side Action Functions

For local actions (no server round-trip), use action.functionCall:

tsx

Agent triggers:

json

Note: Use "call" not "name" for functionCall (A2UI v0.9 spec).

Live Examples

Try these in the Playground:

  • Two-Way Binding: See TextField update Text in real-time
  • Reactive Flow Demo: Type and click "Submit" to see context resolution
  • sendDataModel: Enable in createSurface, check action log's "dataModel" field
  • Context Functions: See formatDate resolve timestamp when button clicked
  • Nested Context: Complex nested objects with path bindings
Previous
Components
Next
Transport