The SDK for A2UI protocol.

NOTE: this is NOT the official SDK maintained by the A2UI team.

Supports all components in A2UI standard catalog out of the box. Built with shadcn/ui and Tailwind CSS.

Currently both A2UI protocol v0.8 and v0.9 (as of draft 2026-01-12) are supported.

Packages

This SDK provides different levels of APIs to suit various use cases:

Package	Description
`@a2ui-sdk/react`	React components for rendering A2UI protocol. Use this for rendering A2UI surfaces in React applications.
`@a2ui-sdk/utils`	Utility functions for A2UI protocol (e.g., string interpolation, path utilities). Use this when building custom renderers.
`@a2ui-sdk/types`	TypeScript type definitions for A2UI protocol. Use this for type-safe A2UI message handling.

// React renderer - full rendering solution
import { A2UIProvider, A2UIRenderer } from '@a2ui-sdk/react/0.8'

// Utilities - for custom renderer implementations
import { resolveValue } from '@a2ui-sdk/utils/0.8'

// Types only - for type-safe message handling
import type { A2UIMessage, A2UIAction } from '@a2ui-sdk/types/0.8'

Installation

npm install @a2ui-sdk/react

V0.8

Usage

First, use the @source directive to tell Tailwind to scan the library code for class names in your global CSS:

@source "../node_modules/@a2ui-sdk/react";

Next, use A2UIProvider and A2UIRenderer to render A2UI messages:

import {
  A2UIProvider,
  A2UIRenderer,
  type A2UIMessage,
  type A2UIAction,
} from '@a2ui-sdk/react/0.8'

function App() {
  const messages: A2UIMessage[] = []

  const handleAction = (action: A2UIAction) => {
    console.log('Action received:', action)
  }

  return (
    <A2UIProvider messages={messages}>
      <A2UIRenderer onAction={handleAction} />
    </A2UIProvider>
  )
}

Custom components

You can override default components or add new custom components via the catalog prop on A2UIProvider. Use standardCatalog as a base and extend it with your custom components.

import {
  A2UIProvider,
  A2UIRenderer,
  standardCatalog,
  type A2UIMessage,
  type A2UIAction,
} from '@a2ui-sdk/react/0.8'

// Extend standard catalog with custom components
const customCatalog = {
  ...standardCatalog,
  components: {
    ...standardCatalog.components,
    // Override default Button component with a custom one
    Button: CustomButtonComponent,
    // Add a new custom Switch component
    Switch: CustomSwitchComponent,
  },
}

function App() {
  return (
    <A2UIProvider catalog={customCatalog} messages={messages}>
      <A2UIRenderer onAction={handleAction} />
    </A2UIProvider>
  )
}

Implementing a custom button component with action dispatch:

import {
  useDispatchAction,
  ComponentRenderer,
  type ButtonComponentProps,
} from '@a2ui-sdk/react/0.8'

export function CustomButtonComponent({
  surfaceId,
  componentId,
  child,
  action,
}: ButtonComponentProps) {
  const dispatchAction = useDispatchAction()

  const handleClick = () => {
    if (action) {
      dispatchAction(surfaceId, componentId, action)
    }
  }

  return (
    <button onClick={handleClick}>
      <ComponentRenderer surfaceId={surfaceId} componentId={child} />
    </button>
  )
}

Implementing a custom switch component with data binding:

import { useDataBinding, useFormBinding } from '@a2ui-sdk/react/0.8'

export function CustomSwitchComponent({
  surfaceId,
  componentId,
  label,
  value,
}: SwitchComponentProps) {
  const labelText = useDataBinding<string>(surfaceId, label, '')
  const [checked, setChecked] = useFormBinding<boolean>(surfaceId, value, false)

  const handleChange = (newChecked: boolean) => {
    setChecked(newChecked)
  }

  return (
    <Switch checked={checked} onChange={handleChange}>
      {labelText}
    </Switch>
  )
}

V0.9

Usage

First, use the @source directive to tell Tailwind to scan the library code for class names in your global CSS:

@source "../node_modules/@a2ui-sdk/react";

Next, use A2UIProvider and A2UIRenderer to render A2UI messages:

import {
  A2UIProvider,
  A2UIRenderer,
  type A2UIMessage,
  type A2UIAction,
} from '@a2ui-sdk/react/0.9'

function App() {
  const messages: A2UIMessage[] = []

  const handleAction = (action: A2UIAction) => {
    console.log('Action received:', action)
  }

  return (
    <A2UIProvider messages={messages}>
      <A2UIRenderer onAction={handleAction} />
    </A2UIProvider>
  )
}

Additionally, override or extend the standard catalog the same way as in v0.8.