@syncfusion/ej2-react-a2ui

Syncfusion EJ2 React component adapter for the A2UI agent-to-UI protocol (v0.9).

This package lets an AI agent emit rich, interactive UIs that are rendered with Syncfusion's production-grade EJ2 React components (Grid, Chart, Gantt, Maps, Scheduler, Spreadsheet, DocumentEditor, PdfViewer, etc.) inside any host application that uses the A2UI protocol.

import { useState, useEffect, useRef } from 'react';
import { syncfusionCatalog, SyncfusionA2UIProvider } from '@syncfusion/ej2-react-a2ui';
import { MessageProcessor } from '@a2ui/web_core/v0_9';
import type { SurfaceModel } from '@a2ui/web_core/v0_9';
import type { ReactComponentImplementation } from '@a2ui/react/v0_9';

// Minimal A2UI message list that renders a Syncfusion Grid with two employee rows.
// processMessages() accepts A2uiMessage[] (one message per array item).
const GRID_MESSAGES = [
  {
    version: 'v0.9' as const,
    createSurface: { surfaceId: 'surface-1', catalogId: 'syncfusion-a2ui-catalog' },
  },
  {
    version: 'v0.9' as const,
    updateComponents: {
      surfaceId: 'surface-1',
      components: [
        { id: 'root', component: 'Column', gap: '16px', padding: '24px', children: ['grid1'] },
        {
          id: 'grid1',
          component: 'SyncfusionDataGrid',
          width: '100%',
          height: '320px',
          dataSource: { path: '/rows' },
          allowPaging: true,
          pageSettings: { pageSize: 5 },
          allowSorting: true,
          columns: [
            { field: 'id',         headerText: 'Employee ID', width: 140 },
            { field: 'name',       headerText: 'Name',        width: 180 },
            { field: 'department', headerText: 'Department',  width: 160 },
          ],
        },
      ],
    },
  },
  {
    version: 'v0.9' as const,
    updateDataModel: {
      surfaceId: 'surface-1',
      path: '/rows',
      value: [
        { id: 'EMP001', name: 'Emma Johnson', department: 'Engineering' },
        { id: 'EMP002', name: 'James Wilson', department: 'Sales' },
      ],
    },
  },
];

function App() {
  const [surface, setSurface] = useState<SurfaceModel<ReactComponentImplementation> | null>(null);

  const processor = useRef(
    new MessageProcessor<ReactComponentImplementation>([syncfusionCatalog]),
  ).current;

  useEffect(() => {
    const sub = processor.onSurfaceCreated(setSurface);
    return () => sub.unsubscribe();
  }, [processor]);

  const renderGrid = () => processor.processMessages(GRID_MESSAGES);

  return (
    <div>
      {!surface && (
        <button onClick={renderGrid}>Render Employee Grid</button>
      )}
      {surface && <SyncfusionA2UIProvider surface={surface} />}
    </div>
  );
}
export default App

Table of contents

• Features
• Prerequisites
• Installation
• Quick start
• Available components
• Public API
• Theming

Features

• 55+ production-ready Syncfusion EJ2 components mapped to A2UI components with full Zod schemas and action callbacks.
• Drop-in replacement for @a2ui/react — use <SyncfusionA2UIProvider /> instead of <A2uiSurface /> and import the catalog from this package.
• Bidirectional data binding — every component writes back to the A2UI DataModel via the auto-generated set* setters and well-known paths such as /selectedValue, /selectedText, /selectedId, /selectedRowJson, etc.
• Defensive direct write-back — alongside the binder-injected setter, adapters also write the value directly to the bound DataModel path so the value is always present in action context, regardless of agent wiring.
• Lazy module injection — only the EJ2 feature modules the agent actually uses are bundled into the running renderer.
• Tree-shakable ESM build with TypeScript declarations, generated by tsup.
• Externalised runtime dependencies — @a2ui/*, Syncfusion packages, react, react-dom, and zod are never bundled into the ESM output. The host app supplies one singleton of each, which npm resolves automatically via the dependency graph.
• sideEffects: false + per-component sub-path exports (., ./catalog, ./provider, ./error-boundary) for fine-grained bundle control.

Prerequisites

| Tool | Version | Notes | | --- | --- | --- | | Node.js | >= 18.0.0 | Required by tsup and the published engines.node field. | | npm | >= 9 | npm is the only supported package manager. The package's postinstall script mutates node_modules to deduplicate @a2ui/web_core; this step is only safe under npm. pnpm and yarn are not supported in this release. | | zod | ^3.25.76 | instanceof checks require a single copy. | | TypeScript (optional) | >= 5.4 | Only required if you consume the published .d.ts files. |

Note — @a2ui/react and @a2ui/web_core are declared as regular dependencies of this package, so npm will install them automatically as transitive dependencies. You only need to import them and zod directly if your own host-app code references them (e.g. for typing SurfaceModel<ReactComponentImplementation>). Whichever version of zod you use must be a single shared instance — install at most one zod version per bundle.

Installation

Installing this package brings @a2ui/react, @a2ui/web_core, the Syncfusion EJ2 packages, and zod along with it as dependencies, so a single command is enough:

# npm
npm install @syncfusion/ej2-react-a2ui

you only need to install them explicitly if your own code imports them directly. The exact same zod instance must be shared, so install at most one zod version in your node_modules.

Quick start

1. Wire the processor and the surface

// App.tsx
import { useEffect, useRef, useState } from 'react';
import {
  syncfusionCatalog,
  SyncfusionA2UIProvider,
} from '@syncfusion/ej2-react-a2ui';
import { MessageProcessor } from '@a2ui/web_core/v0_9';
import type { SurfaceModel } from '@a2ui/web_core/v0_9';
import type { ReactComponentImplementation } from '@a2ui/react/v0_9';

const AGENT_URL = 'http://localhost:10007';

function App() {
  const [surface, setSurface] = useState<SurfaceModel<ReactComponentImplementation> | null>(null);
  const [query, setQuery] = useState('');
  const [loading, setLoading] = useState(false);

  const processorRef = useRef<MessageProcessor<ReactComponentImplementation> | null>(null);

  if (!processorRef.current) {
    processorRef.current = new MessageProcessor<ReactComponentImplementation>(
      [syncfusionCatalog],
      async (action) => {
        // Component interactions inside the surface are forwarded to the agent.
        const res = await fetch(AGENT_URL, {
          method: 'POST',
          headers: { 'content-type': 'application/json' },
          body: JSON.stringify({
            jsonrpc: '2.0',
            id: `req-${Date.now()}`,
            method: 'message/send',
            params: {
              message: {
                kind: 'message',
                messageId: `msg-${Date.now()}`,
                role: 'user',
                parts: [{ data: action }],
              },
            },
          }),
        });
        const envelope = await res.json();
        const messages = envelope?.result?.artifacts?.[0]?.parts?.[0]?.data?.a2uiEnvelope;
        if (messages) processorRef.current!.processMessages(messages);
      },
    );
  }

  const processor = processorRef.current;

  useEffect(() => {
    const sub = processor.onSurfaceCreated(setSurface);
    return () => sub.unsubscribe();
  }, [processor]);

  const sendQuery = async () => {
    if (!query.trim()) return;
    setLoading(true);
    setSurface(null);
    try {
      const res = await fetch(AGENT_URL, {
        method: 'POST',
        headers: { 'content-type': 'application/json' },
        body: JSON.stringify({
          jsonrpc: '2.0',
          id: `req-${Date.now()}`,
          method: 'message/send',
          params: {
            message: {
              kind: 'message',
              messageId: `msg-${Date.now()}`,
              role: 'user',
              parts: [{ text: query }],
            },
          },
        }),
      });
      const envelope = await res.json();
      const messages = envelope?.result?.artifacts?.[0]?.parts?.[0]?.data?.a2uiEnvelope;
      if (messages) processor.processMessages(messages);
    } finally {
      setLoading(false);
    }
  };

  return (
    <div>
      <div style={{ display: 'flex', gap: '8px', padding: '16px' }}>
        <input
          type="text"
          value={query}
          onChange={(e) => setQuery(e.target.value)}
          onKeyDown={(e) => e.key === 'Enter' && sendQuery()}
          placeholder="Ask the agent something…"
          style={{ flex: 1, padding: '8px' }}
        />
        <button onClick={sendQuery} disabled={loading}>
          {loading ? 'Sending…' : 'Send'}
        </button>
      </div>
      {surface && <SyncfusionA2UIProvider surface={surface} />}
    </div>
  );
}
export default App

2. Send messages from the agent

A minimal message from an Agent that renders a Syncfusion Grid:

[
  {
    "version": "v0.9",
    "createSurface": {
      "surfaceId": "workspace",
      "catalogId": "syncfusion-a2ui-catalog"
    }
  },
  {
    "version": "v0.9",
    "updateComponents": {
      "surfaceId": "workspace",
      "components": [
        {
          "id": "root",
          "component": "Column",
          "padding": "24px",
          "gap": "16px",
          "children": [
            "grid1"
          ]
        },
        {
          "id": "grid1",
          "component": "SyncfusionDataGrid",
          "width": "100%",
          "dataSource": {
            "path": "/gridData"
          },
          "allowPaging": true,
          "pageSettings": {
            "pageSize": 5
          },
          "allowSorting": true,
          "columns": [
            {
              "field": "id",
              "headerText": "ID",
              "width": "100",
              "textAlign": "Right"
            },
            {
              "field": "name",
              "headerText": "Name",
              "width": "180"
            },
            {
              "field": "role",
              "headerText": "Role",
              "width": "180"
            }
          ]
        }
      ]
    }
  },
  {
    "version": "v0.9",
    "updateDataModel": {
      "surfaceId": "workspace",
      "path": "/gridData",
      "value": [
        {
          "id": 1,
          "name": "Alice",
          "role": "Manager"
        },
        {
          "id": 2,
          "name": "Bob",
          "role": "Developer"
        },
        {
          "id": 3,
          "name": "Charlie",
          "role": "Designer"
        }
      ]
    }
  }
]

Available components

| Component | Description | | --- | --- | | SyncfusionDataGrid | Paged, sortable, filterable, editable, virtualised data grid. | | SyncfusionTreeGrid | Hierarchical grid with parent/child mapping. | | SyncfusionChart | 30+ chart types (line, bar, area, spline, stacking, radar, polar, bubble, range, hilo, waterfall, histogram, …). | | Syncfusion3DChart | 3D column / bar variants. | | SyncfusionHeatMap | Heat map for density / matrix / risk visualisation. | | SyncfusionMaps | Geographic map with markers, layers, and route rendering. | | SyncfusionScheduler | Day / week / work-week / month / agenda / timeline / year views. | | SyncfusionCalendar | Inline calendar with min/max, weekend disable, multi-select. | | SyncfusionDatePicker | Single-date picker. | | SyncfusionDateRangePicker | Start + end date selection. | | SyncfusionDateTimePicker | Date + time selection. | | SyncfusionTimePicker | Time-of-day selection. | | SyncfusionButton | Standard, primary, toggle, block; left/right icon. | | SyncfusionSplitButton | Button with a dropdown menu. | | SyncfusionDropDownButton | Dropdown button with menu items. | | SyncfusionProgressButton | Button with progress animation. | | SyncfusionSpeedDial | Floating action button with menu. | | SyncfusionChipList | Chip list with selection, deletion, leading/trailing icons. | | SyncfusionCheckBox | Single checkbox with label, indeterminate state. | | SyncfusionRadioButton | Radio group; agent supplies name for grouping. | | SyncfusionSwitch | On/off switch with onLabel / offLabel. | | SyncfusionDropDownList | Filterable, clearable single-select. | | SyncfusionComboBox | Typeahead combobox. | | SyncfusionMultiSelect | Multi-select dropdown. | | SyncfusionListView | Selectable, checkable list with header and virtualisation. | | SyncfusionCard | Card with title, subtitle, and children. | | SyncfusionAppBar | Top app bar (regular / dense / prominent). | | SyncfusionTabs | Tabs with A2UI child content rendered via portals. | | SyncfusionStepper | Horizontal / vertical stepper, linear or non-linear. | | SyncfusionToolbar | Toolbar with overflow, items, click events. | | SyncfusionMenu | Vertical menu with sub-menus. | | SyncfusionBreadcrumb | Breadcrumb navigation. | | SyncfusionPager | Numeric / previous-next pager. | | SyncfusionRating | Star rating with precision and reset. | | SyncfusionNumericTextBox | Numeric input with min/max/step/decimals. | | SyncfusionTextBox | Single-line text input. | | SyncfusionTextArea | Multi-line text input. | | SyncfusionMaskedTextBox | Masked input. | | SyncfusionColorPicker | Color picker. | | SyncfusionSlider | Numeric slider. | | SyncfusionOTPInput | One-time-password input. | | SyncfusionBadge | Numeric / text badge. | | SyncfusionMessage | Severity-styled inline message. | | SyncfusionSpinner | Loading spinner. | | SyncfusionSkeleton | Placeholder skeleton. | | SyncfusionToast | Toast notifications with severity levels. | | SyncfusionRichTextEditor | WYSIWYG / Markdown editor with toolbar. | | SyncfusionBlockEditor | Block-based content editor. | | SyncfusionDocumentEditorContainer | Rich WYSIWYG document authoring (DOCX-style) with sections, headers/footers, tables, and review. | | SyncfusionPdfViewer | In-browser PDF viewer with toolbar, search, print, download, and form-fill. | | SyncfusionDiagram | Diagram editor with nodes, connectors, and auto-layout. | | SyncfusionGanttChart | Gantt chart with task dependencies, duration, progress, milestones, and critical path. | | SyncfusionSpreadsheet | Excel-compatible spreadsheet. | | SyncfusionBarcodeGenerator | Configurable 1D barcode generator. | | SyncfusionQRCode | QR code generator. | | SyncfusionDataMatrix | Data Matrix 2D barcode generator. | | SyncfusionInPlaceEditor | Inline editor wrapper. | | SyncfusionAvatar | Avatar / initials / image. |

Plus all basic A2UI primitives (Column, Row, Text, Image, Icon, Divider, …) from basicCatalog, which is bundled inside syncfusionCatalog.

Every component has a matching *.api.ts file that exports a Zod schema and a ComponentApi object, plus a *SchemaType type alias you can use to generate typed A2UI messages from your agent SDK.

Theming

Syncfusion EJ2 widgets need a CSS theme from the @syncfusion/ej2-* packages. The package does not ship a theme stylesheet — pick one and import it yourself, e.g.:

import '@syncfusion/ej2-grids/styles/material.css';
import '@syncfusion/ej2-react-charts/styles/material.css';
// ... or the matching `tailwind3` / `bootstrap5` / `fluent2` variant

Public API

Most apps only need:

import { syncfusionCatalog, SyncfusionA2UIProvider } from '@syncfusion/ej2-react-a2ui';

Sub-path exports

// Just the catalog — saves bytes when the host app already imports
// the Syncfusion components directly.
import { syncfusionCatalog } from '@syncfusion/ej2-react-a2ui/catalog';

// Just the provider — useful for small wrapping apps.
import { SyncfusionA2UIProvider } from '@syncfusion/ej2-react-a2ui/provider';

Support and feedback

• For any other queries, reach our Syncfusion support team or post the queries through the Community forums and submit a feature request or a bug through our Feedback portal.
• To renew the subscription, click renew or contact our sales team at [email protected] | Toll Free: 1-888-9 DOTNET.

About Syncfusion

Founded in 2001 and headquartered in Research Triangle Park, N.C., Syncfusion has more than 29,000 customers and more than 1 million users, including large financial institutions, Fortune 500 companies, and global IT consultancies.

Today we provide 1,800+ controls and frameworks for web (ASP.NET Core, ASP.NET MVC, ASP.NET WebForms, JavaScript, Angular, React, Vue, and Blazor, mobile (Xamarin, Flutter, UWP, and JavaScript), and desktop development (WinForms, WPF, and UWP and WinUI)). We provide ready-to deploy enterprise software for dashboards, reports, data integration, and big data processing. Many customers have saved millions in licensing fees by deploying our software.