@syncfusion/ej2-angular-a2ui

Syncfusion EJ2 Angular 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 Angular components (Grid, Chart, Gantt, Maps, Scheduler, Spreadsheet, RichTextEditor, DocumentEditor, PdfViewer, Toast, plus the basic A2UI primitives) inside any host application that uses the A2UI protocol.

Table of contents

• Features
• Prerequisites
• Installation
• Quick start
• Available components
• Theming
• Public Api
• Support and feedback
• About Syncfusion

Features

• 55+ production-ready Syncfusion EJ2 components mapped to A2UI components with full Zod schemas and action callbacks.
• Standalone A2UI adapter — single catalog id (syncfusion-a2ui-catalog), canonical Syncfusion* component names, Zod schemas for every component, and a single public entry surface generated by ng-packagr.
• provideA2Ui({ catalogs: [syncfusionCatalog] }) — single-line bootstrap helper from @a2ui/angular wires the Syncfusion-augmented catalog into the A2UI runtime. provideSyncfusionCatalog() is also exported as a low-level escape hatch that overrides the default BasicCatalog directly.
• Bidirectional data binding — every component writes back to the A2UI DataModel via 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.
• Conditional module registration — each component registers only the EJ2 feature modules it needs in its Angular providers; the build externalises all EJ2 packages so the host bundler tree-shakes unused feature modules.
• Tree-shakable FESM2022 build with TypeScript declarations, generated by ng-packagr.
• Externalised runtime dependencies — Syncfusion EJ2 Angular modules, @a2ui/angular, @a2ui/web_core, zod, and @angular/* are never bundled into the FESM output. They are declared as regular dependencies, so npm installs them automatically and the host app resolves a single copy via the dependency graph.
• sideEffects: false + a narrow public API for fine-grained bundle control.

Prerequisites

| Tool | Version | Notes | | --- | --- | --- | | Node.js | >=22.0.0 | Required by ng-packagr and the published engines.node field. | | Angular | ^21.0.0 | Pulled in automatically as a dependency of this package. The host app must resolve to a single Angular copy. | | @a2ui/angular | 0.10.7 (exact) | Direct dependency — the A2UI Angular runtime; installed automatically. | | @a2ui/web_core | 0.10.5 (exact) | Direct dependency — shared A2UI types & utilities; installed automatically. | | Syncfusion EJ2 Angular | * | The 26 @syncfusion/ej2-angular-* packages ship as direct dependencies and are installed automatically alongside this package. | | zod | ^3.25.76 | Direct dependency. instanceof checks require a single copy. | | TypeScript (optional) | >= 5.9 | Only required if you consume the published .d.ts files. |

Note — @a2ui/angular, @a2ui/web_core, the Syncfusion EJ2 Angular packages, zod, and the Angular packages are declared as regular dependencies of this package, so npm installs them automatically as transitive dependencies. You only need to import them explicitly if your own host-app code references them directly. 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 the Angular adapter itself plus its runtime dependencies — @a2ui/angular, @a2ui/web_core, the matching Syncfusion EJ2 Angular packages, zod, rxjs, and tslib — along with it, so a single command is enough:

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

You only need to install those packages 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 catalog and the surface

// main.ts
import 'zone.js';
import { bootstrapApplication } from '@angular/platform-browser';
import { provideA2Ui } from '@a2ui/angular/v0_9';
import { syncfusionCatalog } from '@syncfusion/ej2-angular-a2ui';
import { AppComponent } from './app.component';

bootstrapApplication(AppComponent, {
  providers: [provideA2Ui({ catalogs: [syncfusionCatalog] })],
}).catch((err) => console.error(err));

// app.component.ts
import {
  ChangeDetectionStrategy,
  Component,
  signal,
} from '@angular/core';
import { SyncfusionA2UIProvider } from '@syncfusion/ej2-angular-a2ui';
import type { A2uiMessage } from '@a2ui/web_core/v0_9';

@Component({
  standalone: true,
  imports: [SyncfusionA2UIProvider],
  changeDetection: ChangeDetectionStrategy.OnPush,
  selector: 'app-root',
  template: `
    <button (click)="renderGrid()">Render Employee Grid</button>

    @if (msgs(); as messages) {
      <syncfusion-a2ui-provider
        [messages]="messages"
        [dataContextPath]="'/'"
        [onError]="onBoundaryError"
      />
    }
  `,
})
export class AppComponent {
  protected readonly msgs = signal<A2uiMessage[] | null>(null);

  protected onBoundaryError(error: Error): void {
    console.error('[A2UI] surface render error:', error.message);
  }

  protected renderGrid(): void {
    this.msgs.set([
      {
        version: 'v0.9',
        createSurface: {
          surfaceId: 'surface-1',
          catalogId: 'syncfusion-a2ui-catalog',
        },
      },
      {
        version: 'v0.9',
        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',
        updateDataModel: {
          surfaceId: 'surface-1',
          path: '/rows',
          value: [
            { id: 'EMP001', name: 'Emma Johnson', department: 'Engineering' },
            { id: 'EMP002', name: 'James Wilson', department: 'Sales' },
          ],
        },
      },
    ]);
  }
}

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"
        }
      ]
    }
  }
]

Note — SyncfusionDataGrid is the canonical grid component name in this package. It matches the @syncfusion/ej2-angular-grids EJ2 directive used at runtime.

3. Error handling

SyncfusionA2UIProvider renders the surface inside the project's SyncfusionSurfaceErrorBoundary. The boundary owns the onError / renderFallback / fallbackStyle contract — it behaves like React's componentDidCatch and renders the fallback for:

• errors routed through Angular's ErrorHandler (the host's existing ErrorHandler keeps firing, the boundary adds an outbound channel),
• the boundary's exposed .captureError(error) for callers that drive error capture imperatively (e.g. an explicit event handler),
• the provider's captureRenderError(error) shim, which delegates into the boundary for backward compatibility.

<syncfusion-a2ui-provider
  [surface]="surface"
  [renderFallback]="renderFallback"
  [onError]="onError"
  [fallbackStyle]="{ 'border-color': '#dc2626' }"
></syncfusion-a2ui-provider>

For full programmatic control — e.g. silencing the built-in fallback or forwarding errors to your observability stack before they reach the boundary — wire the boundary's createErrorHandler() into your host:

import { ErrorHandler } from '@angular/core';
import {
  SyncfusionSurfaceErrorBoundary,
  SyncfusionA2UIProvider,
} from '@syncfusion/ej2-angular-a2ui';

class SurfaceErrorHandler extends ErrorHandler {
  override handleError(error: unknown): void {
    console.error('[A2UI] unhandled surface error:', error);
    // Forward to your observability stack. The `SurfaceErrorBoundary`
    // already renders its own fallback UI when this fires; a custom
    // handler only adds side effects.
  }
}

// Optional: import the `SurfaceErrorBoundary` once at app bootstrap so
// the boundary registers itself for native Angular throws. Hosting
// apps that don't directly wrap their tree can still rely on the
// provider's automatic boundary mount.

Note — Angular intentionally does not auto-route in-template compile errors through a wrapping boundary the way React does. If you need to catch render-eval failures too, set captureWindowErrors on the provider and forward window.error / unhandledrejection events through your own ErrorHandler.

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.

Public API

Most apps only need:

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

Theming

Syncfusion EJ2 widgets need a CSS theme from the @syncfusion/ej2-angular-* 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-charts/styles/material.css';
// ... or the matching `tailwind3` / `bootstrap5` / `fluent2` variant

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.

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.