A2UI SDK

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 are supported.

⚠️ Important: V0.9 is a draft version based on the A2UI specification as of 2026-01-12. The v0.9 protocol has changed significantly recently and may continue to evolve. We recommend using the stable v0.8 until v0.9 reaches alpha or beta status.

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,
  useA2UIMessageHandler,
  type A2UIMessage,
  type A2UIAction,
} from '@a2ui-sdk/react/0.8'

function App() {
  return (
    <A2UIProvider>
      <MyApp />
    </A2UIProvider>
  )
}

function MyApp() {
  const { processMessage } = useA2UIMessageHandler()

  useEffect(() => {
    const message: A2UIMessage = {
      // ...  A2UI message from your backend
    }
    processMessage(message)
  }, [processMessage])

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

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

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

⚠️ Draft Version Warning: V0.9 is currently a draft implementation based on the A2UI specification as of 2026-01-12. The protocol has changed significantly recently and may continue to evolve. We recommend using the stable v0.8 for production use until v0.9 reaches alpha or beta status.

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,
  useA2UIMessageHandler,
  type A2UIMessage,
  type A2UIAction,
} from '@a2ui-sdk/react/0.9'

function App() {
  return (
    <A2UIProvider>
      <MyApp />
    </A2UIProvider>
  )
}

function MyApp() {
  const { processMessage } = useA2UIMessageHandler()

  useEffect(() => {
    const message: A2UIMessage = {
      // ...  A2UI message from your backend
    }
    processMessage(message)
  }, [processMessage])

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

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

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