Client Setup: Installing A2UI Renderers for Your App

A2UI ships a renderer for every major frontend platform. Pick the one that matches your stack, install it alongside the shared @a2ui/web_core library, and your application is ready to receive, process, and display agent-generated interfaces. Each renderer wraps the same core protocol logic so behaviour is consistent regardless of which framework you choose.

Renderer Overview

React

@a2ui/react — v0.8 & v0.9 · Stable

Lit / Web Components

@a2ui/lit — v0.8 & v0.9 · Stable

Angular

@a2ui/angular — v0.8 & v0.9 · Stable

Flutter (GenUI SDK)

flutter_genui — v0.8 & v0.9 · Stable

Renderer	Platform	v0.8	v0.9	Status
React (`@a2ui/react`)	Web	✅	✅	✅ Stable
Lit (`@a2ui/lit`)	Web	✅	✅	✅ Stable
Angular (`@a2ui/angular`)	Web	✅	✅	✅ Stable
Flutter (`flutter_genui`)	Mobile / Desktop / Web	✅	✅	✅ Stable
Jetpack Compose	Android	—	—	🚧 Planned Q2 2026

For a full list of first-party and community-maintained renderers see the Renderers Reference.

Shared Web Library: `@a2ui/web_core`

All three web renderers — Lit, Angular, and React — are built on top of @a2ui/web_core (v0.10.3). This shared foundation provides the message processor, state management, and data-binding logic that every web renderer needs. Each framework-specific package adds only the rendering layer on top. You should install @a2ui/web_core alongside whichever framework renderer you choose. The shared @a2ui/web_core library provides:

Message Processor — manages A2UI state and processes all incoming agent messages.
Protocol schemas — Zod-validated message schemas for v0.8 and v0.9.
Basic Catalog — a minimal out-of-the-box component set (@a2ui/web_core/v0_9/basic_catalog).

Component Catalogs

A catalog is a JSON Schema file that tells the agent exactly which components, functions, and themes are available. A2UI ships a Basic Catalog to get you started, but most production applications will define their own catalog to match their design system.

Your design system is what matters. You can register any collection of components and functions, and A2UI will use them. See Defining Your Own Catalog for details.

Web Components (Lit)

The Lit renderer turns A2UI messages into native Web Components, making it usable from any framework — or no framework at all.

Install packages

npm install @a2ui/lit @a2ui/web_core

Import the versioned entry point

Use the versioned import that matches your agent’s protocol version:

// v0.9
import '@a2ui/lit/v0_9';

// v0.8
import '@a2ui/lit/v0_8';

Add the surface to your HTML

Place the <a2ui-surface> custom element wherever you want agent-generated UI to appear:

<a2ui-surface surface-id="main"></a2ui-surface>

The Lit renderer uses Lit Signals for reactive state management, so the surface updates automatically whenever the message processor receives new data from the agent.

The Lit renderer provides:

Message Processor — wraps @a2ui/web_core’s processor with Lit-reactive bindings.
<a2ui-surface> component — renders A2UI surfaces as a standard custom element.
Lit Signals — reactive state management for automatic, efficient UI updates.

Working example: The Lit shell sample on GitHub includes a full README with detailed run instructions.

Angular

The Angular renderer integrates cleanly with Angular’s dependency injection system, exposing a service and a dynamic component host that you configure through a standard provider token.

Install packages

npm install @a2ui/angular @a2ui/web_core

The Angular renderer requires Angular ^21.2.5 as a peer dependency.

Configure application providers

A2UI uses versioned imports for its protocol-specific implementations. For v0.9, configure your ApplicationConfig as follows:

import { ApplicationConfig } from '@angular/core';
import {
  A2UI_RENDERER_CONFIG,
  A2uiRendererService,
  BasicCatalog,
} from '@a2ui/angular/v0_9';

export const appConfig: ApplicationConfig = {
  providers: [
    {
      provide: A2UI_RENDERER_CONFIG,
      useFactory: () => ({
        catalogs: [new BasicCatalog()],
        actionHandler: action => {
          console.log('Action dispatched:', action);
        },
      }),
    },
    A2uiRendererService,
  ],
};

Add the component host to your template

Use a2ui-v09-component-host in any Angular template to render the agent-generated surface:

<a2ui-v09-component-host [surfaceId]="'main'" />

The Angular renderer provides:

A2uiRendererService — manages the A2UI message processor and reactive model.
a2ui-v09-component-host — a dynamic component host that renders A2UI components from a surface.
A2UI_RENDERER_CONFIG token — configures catalogs and action handlers via Angular DI.

Streaming

By default, the Angular renderer uses the streaming API. To disable streaming when running the sample app inside the A2UI monorepo, set the environment variable before starting:

export ENABLE_STREAMING=false
yarn start restaurant

The yarn start command above is specific to the A2UI monorepo sample applications. For standalone projects, use the package manager of your choice (npm, pnpm, yarn, etc.).

Working examples: See the Angular samples on GitHub.

React

The React renderer follows familiar React patterns — a class-based message processor, a surface component, and a hook for accessing the processor anywhere in the tree.

Install packages

npm install @a2ui/react @a2ui/web_core

The React renderer requires react and react-dom ^19.2.7 as peer dependencies.

Import the versioned entry point

Use the versioned import that matches the protocol version your agent targets:

v0.9
v0.8

import { A2uiSurface, basicCatalog } from '@a2ui/react/v0_9';
import { MessageProcessor } from '@a2ui/web_core/v0_9';

import { MessageProcessor, A2UIRenderer, useA2UI } from '@a2ui/react/v0_8';

Set up the message processor and render a surface

Create a MessageProcessor instance (imported from @a2ui/web_core/v0_9), feed it agent messages, and place <A2uiSurface> where you want the generated UI to appear:

import { useMemo, useState, useEffect } from 'react';
import { A2uiSurface, basicCatalog, ReactComponentImplementation } from '@a2ui/react/v0_9';
import { MessageProcessor, SurfaceModel } from '@a2ui/web_core/v0_9';

export function App() {
  const processor = useMemo(
    () => new MessageProcessor([basicCatalog], action => console.log('Action:', action)),
    [],
  );
  const [surfaces, setSurfaces] = useState<SurfaceModel<ReactComponentImplementation>[]>([]);

  useEffect(() => {
    const s1 = processor.onSurfaceCreated(s => setSurfaces(p => [...p, s]));
    const s2 = processor.onSurfaceDeleted(id => setSurfaces(p => p.filter(s => s.id !== id)));
    return () => { s1.unsubscribe(); s2.unsubscribe(); };
  }, [processor]);

  return (
    <>
      {surfaces.map(surface => (
        <A2uiSurface key={surface.id} surface={surface} />
      ))}
    </>
  );
}

The React renderer provides:

MessageProcessor class (from @a2ui/web_core/v0_9) — manages A2UI state and processes incoming messages.
<A2uiSurface> component (from @a2ui/react/v0_9) — renders an agent-generated surface in your React app.
basicCatalog — the built-in component catalog, passed to MessageProcessor at construction time.

Working example: The React shell sample on GitHub shows a complete integration.

Flutter (GenUI SDK)

Flutter uses the first-party GenUI SDK, which provides native A2UI rendering across mobile, desktop, and web targets.

Add the package

flutter pub add flutter_genui

Follow the GenUI getting-started guide

The GenUI SDK has its own dedicated documentation covering widget setup, protocol configuration, and catalog registration for Flutter.

Connecting to Agents

Once your renderer is installed, your client application needs to complete three tasks:

Receive A2UI messages from the agent

Choose a transport mechanism appropriate for your use case:

Server-Sent Events (SSE) — one-way streaming from server to client.
WebSockets — bidirectional real-time communication.
A2A Protocol — standardised agent-to-agent communication with built-in A2UI support.

See the Transports reference for details.

Process messages with the Message Processor

Feed each received message into the renderer’s MessageProcessor. The processor validates, parses, and applies each message to the live UI state.See samples/client/lit/shell/client.ts for an example using the A2A protocol client.

Send user actions back to the agent

When users interact with A2UI components (clicking buttons, submitting forms), the client:

Captures the @a2uiaction event from the component.
Resolves any data context required for the action.
Sends the action payload to the agent.
Processes the agent’s response messages.

See the @a2uiaction event handler in samples/client/lit/shell/app.ts for examples of handling button clicks and form submissions.

Error Handling

Common errors to handle in your client integration:

Error	Cause
Invalid Surface ID	Surface referenced before `beginRendering` (v0.8) or `createSurface` (v0.9) was received.
Invalid Component ID	Component IDs must be unique within a surface.
Invalid Data Path	Check the data model structure and JSON Pointer syntax.
Schema Validation Failed	Verify the message format matches the A2UI specification.

See the try...catch blocks in #sendMessage in samples/client/lit/shell/app.ts for examples of handling communication errors gracefully.

Next Steps

Theming & Styling

Customize colors, fonts, and dark mode to match your brand.

Defining Your Own Catalog

Restrict the agent to your design system’s components.

A2UI with Any Agent Framework

Use AG-UI and CopilotKit to connect any agent framework.

Protocol Reference

Deep-dive into A2UI message schemas and the protocol specification.

Get Started

Client Integration

Agent Development

Building Renderers

Ecosystem

Client Setup: Installing A2UI Renderers for Your App

Renderer Overview

React

Lit / Web Components

Angular

Flutter (GenUI SDK)

Shared Web Library: `@a2ui/web_core`

Component Catalogs

Web Components (Lit)

Angular

Streaming

React

Flutter (GenUI SDK)

Connecting to Agents

Error Handling

Next Steps

Theming & Styling

Defining Your Own Catalog

A2UI with Any Agent Framework

Protocol Reference

Build docs developers (and LLMs) love

Get Started

Client Integration

Agent Development

Building Renderers

Ecosystem

Documentation Index

​Renderer Overview

React

Lit / Web Components

Angular

Flutter (GenUI SDK)

​Shared Web Library: @a2ui/web_core

​Component Catalogs

​Web Components (Lit)

​Angular

​Streaming

​React

​Flutter (GenUI SDK)

​Connecting to Agents

​Error Handling

​Next Steps

Theming & Styling

Defining Your Own Catalog

A2UI with Any Agent Framework

Protocol Reference

Build docs developers (and LLMs) love

Renderer Overview

Shared Web Library: `@a2ui/web_core`

Component Catalogs

Web Components (Lit)

Angular

Streaming

React

Flutter (GenUI SDK)

Connecting to Agents

Error Handling

Next Steps