Getting Started with Syncfusion A2UI

09 Sep 202611 minutes to read

This section walks through creating a simple React app that renders a Syncfusion EJ2 React component from a list of A2UI v0.9 messages using the Syncfusion A2UI for React package. The example below uses a DataGrid for illustration, but the same pattern — define an A2UI v0.9 message list, feed it to a MessageProcessor configured with syncfusionCatalog, and render the result with <SyncfusionA2UIProvider/> — works for every component in the catalog (Chart, Scheduler, Calendar, RichTextEditor, Diagram, Spreadsheet and more).

Prerequisites

The following tools and runtime are required to build and run a Syncfusion A2UI React application.

Tool Version
Node.js 18 LTS or higher

React supported versions

React version Minimum @syncfusion/ej2-react-* version
React v19 29.1.33 and above
React v18 20.2.36 and above
React v17 18.3.50 and above

Set up a development environment

To set up a React application quickly, use create-vite, which provides a faster development environment, smaller bundle sizes, and optimized builds. Vite sets up the environment using JavaScript and optimizes applications for production.

To create a new React application, run one of the following commands based on your preferred language:

React with JavaScript

npm create vite@latest my-app -- --template react

React with TypeScript

npm create vite@latest my-app -- --template react-ts

Both commands scaffold a Vite project named my-app using the selected template and skip interactive prompts because the --template flag is supplied. If you omit the flag, Vite will instead walk you through framework, variant, and linter selection interactively.

After the scaffold completes, install the dependencies and start the dev server once to confirm the project is wired up:

cd my-app
npm install
npm run dev

Verify the Vite dev server starts (the terminal prints a http://localhost:5173/ URL), then stop it and proceed to the next step. You do not need to navigate again; the cd my-app above already places you in the project directory.

Install the Syncfusion A2UI React package

The Syncfusion A2UI for React package is published to the npm registry. It bundles the A2UI v0.9 runtime, all Syncfusion EJ2 React adapters, and Zod as regular dependencies, so a single install line is enough:

npm install @syncfusion/ej2-react-a2ui

Install a Syncfusion theme package

Themes for Syncfusion React components can be applied using CSS or SASS files from the npm theme packages, CDN, CRG, or Theme Studio.

This guide uses the Tailwind 3 theme as an example. In this package, each component includes an index.css file that automatically loads all the required dependency styles. To install the Tailwind 3 theme package, use the following command:

npm install @syncfusion/ej2-tailwind3-theme

Replace @syncfusion/ej2-tailwind3-theme with the theme package that matches your design system.

Clear Vite’s default styles

By default, Vite projects include a src/index.css file with default styles. These default styles may conflict with Syncfusion component styles. Clear all content from src/index.css to prevent style conflicts.

Import the component styles

The required styles for each component family the agent will render are imported in the src/App.css file. The example below imports the stylesheet for the DataGrid used in the getting-started code sample; add an @import line for every additional component family the agent may use (chips, buttons, schedule, chart, etc.):

@import "@syncfusion/ej2-tailwind3-theme/styles/grid/index.css";

Render your first Syncfusion A2UI surface

Replace the contents of src/App.tsx with the snippet below. It wires up the MessageProcessor with syncfusionCatalog, subscribes to onSurfaceCreated, and processes three A2UI v0.9 messages that together render a DataGrid with two employee rows.

import { useState, useEffect, useRef } from 'react';
import { ButtonComponent } from '@syncfusion/ej2-react-buttons';
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';
import './App.css';

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 && (
                <ButtonComponent onClick={renderGrid}>Render Employee Grid</ButtonComponent>
            )}
            {surface && <SyncfusionA2UIProvider surface={surface} />}
        </div>
    );
}
export default App

What the snippet does, in order:

  1. Imports the SyncfusionA2UIProvider and syncfusionCatalog from the package, plus the MessageProcessor and types from @a2ui/web_core/v0_9 and @a2ui/react/v0_9.
  2. Declares a static MESSAGES array with three A2UI v0.9 messages: a createSurface, an updateComponents that adds a Column containing a SyncfusionDataGrid, and an updateDataModel that supplies the grid’s rows.
  3. Creates the MessageProcessor once inside useRef so it survives re-renders, and registers syncfusionCatalog as the catalog it should resolve components against.
  4. In the useEffect, subscribes to onSurfaceCreated (so the latest SurfaceModel lands in component state) and immediately calls processor.processMessages(MESSAGES) to render the surface.
  5. Renders the surface with <SyncfusionA2UIProvider surface={surface} />. The provider is generic, swap SyncfusionDataGrid for any other component in the catalog (SyncfusionChart, SyncfusionScheduler, SyncfusionCalendar, SyncfusionTextBox, …) and the same pipeline renders it.

Run the application

Run the application using the following command:

npm run dev

Open the generated local URL (typically, http://localhost:5173/) in the browser.

Click Render Employee Grid. The sample grid renders as follows:

Syncfusion A2UI getting-started output

The application displays a Syncfusion EJ2 DataGrid with the two employee rows, paging, and sorting enabled, rendered entirely from the static A2UI v0.9 message list above.

Verify the application

Confirm the surface is wired up end-to-end:

  1. The browser loads the Vite dev URL without console errors.
  2. Clicking Render Employee Grid triggers a surface render — the DataGrid appears with two rows, ID and Name columns, plus the grid features such as sorting, searching, and paging
  3. Resize a column header, change a page, or sort a column. Each interaction should be smooth, with no React warnings in the browser console.
  4. Open the browser DevTools Network tab and reload the page — verify that no data requests leave the browser when the grid renders. This proves the MessageProcessor synthesized the surface entirely from the static MESSAGES array in src/App.tsx, with no external backend in the loop.

If any step fails, check the browser console for Zod-schema validation errors — most failures at this point are caused by a miscopying MESSAGES array or a missing syncfusionCatalog registration.

Register the Syncfusion license key

Syncfusion® EJ2 React components require a valid license key to be registered before they render without a trial-license watermark. The A2UI adapters call into the same EJ2 components under the hood, so a registered key is required even when the UI itself is generated by an agent.

For instructions on generating and registering a license key, see:

See also