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. /Usage
IntroductionInstallationUsageComponentsThemingRTL SupportCustom ComponentsActionsTransportAPI Reference

Usage

Quick start guide and basic usage examples for rendering A2UI surfaces with the A2UISurface component.

Basic Usage

The <A2UISurface> Component

The core of a2ui-shadcn is the <A2UISurface> component. It handles:

  • Parsing A2UI JSON messages
  • Managing component state and data model
  • Rendering UI components
  • Handling user interactions

Minimal Example

tsx

Manual Message Mode

For testing or server-side rendering, provide messages directly:

tsx

WebSocket Transport

For real-time bidirectional communication:

tsx

Server-Sent Events (SSE)

For one-way streaming from server to client:

tsx

Handling Actions

Actions are triggered by user interactions (button clicks, form submissions, etc.):

tsx

Custom Component Registry

Extend the catalog with your own components:

tsx

Your custom component receives A2UI props:

tsx

Theme Customization

Override default theme tokens:

tsx

RTL Layout

Enable right-to-left layout:

tsx

Agents can also control direction via createSurface:

json

Error Handling

Handle surface-level errors:

tsx

Next Steps

  • Components Reference - Explore all available components
  • Theming Guide - Customize colors and typography
  • API Reference - Complete TypeScript API docs
Previous
Installation
Next
Components