Skip to content

Type to search the docs, or jump to:

Authoring Universal Web Components

Universal components let you write a custom A2UI Web Component once with A2uiLitElement and register it directly in Lit, React, and Angular catalogs without per-framework wrappers. You declare the component’s property contract with a Zod schema, and @a2ui/web_core resolves data bindings, function calls, child references, and actions before passing values to your element.

Install @a2ui/web_core, lit, and zod alongside the renderer package for your host framework (@a2ui/lit, @a2ui/react, or @a2ui/angular):

Terminal window
npm install @a2ui/web_core lit zod

Step 1: Define the component schema

Create a ComponentApi object with the component name used in A2UI JSON payloads and a Zod schema describing its properties. Use DynamicStringSchema so each field accepts either a literal string or a data-model binding (see Catalogs, Components, and Functions and How to Define a Catalog).

stat-card.api.ts
import {z} from 'zod';
import {type ComponentApi} from '@a2ui/web_core';
import {DynamicStringSchema} from '@a2ui/web_core/v1_0';
export const StatCardApi = {
name: 'StatCard',
schema: z.object({
label: DynamicStringSchema,
value: DynamicStringSchema,
}),
} satisfies ComponentApi;

Step 2: Build the custom element

Extend A2uiLitElement parameterized with typeof StatCardApi, read resolved values from this.controller.props, and export a WebComponentImplementation pairing the API with tagName and element.

HTML custom element tagName values such as 'a2ui-stat-card' require a hyphen under the W3C Custom Elements specification. By contrast, A2UI v1.0 surface component id values in JSON payloads must be valid Unicode identifiers (UAX #31) such as 'revenue_card' or 'revenueCard', without hyphens.

stat-card.ts
import {css, html} from 'lit';
import {A2uiLitElement, type WebComponentImplementation} from '@a2ui/web_core/universal';
import {StatCardApi} from './stat-card.api.js';
export class StatCardElement extends A2uiLitElement<typeof StatCardApi> {
static override styles = css`
:host {
display: block;
padding: 16px;
border: 1px solid var(--border-color, #e2e8f0);
border-radius: 8px;
}
.label {
font-size: 0.875rem;
color: #64748b;
}
.value {
font-size: 1.5rem;
font-weight: 700;
}
`;
protected override readonly api = StatCardApi;
override render() {
const {label, value} = this.controller.props;
return html`
<div class="label">${typeof label === 'string' ? label : ''}</div>
<div class="value">${typeof value === 'string' ? value : ''}</div>
`;
}
}
export const statCardComponent: WebComponentImplementation<typeof StatCardApi.schema> = {
...StatCardApi,
tagName: 'a2ui-stat-card',
element: StatCardElement,
};

Step 3: Register the component in your app

Add statCardComponent to a catalog alongside the optional Basic Catalog components (or your own custom component set) and pass that catalog to your framework’s renderer. Host renderers register a2ui-stat-card in customElements automatically when mounting the surface.

import {html, render} from 'lit';
import '@a2ui/lit';
import {Catalog, MessageProcessor} from '@a2ui/web_core';
import {BASIC_FUNCTIONS, basicCatalog} from '@a2ui/web_core/catalogs/basic/v1';
import {statCardComponent} from './stat-card.js';
const analyticsCatalog = new Catalog(
'https://example.com/catalogs/analytics/v1/catalog.json',
'1.0',
[...basicCatalog.components.values(), statCardComponent],
BASIC_FUNCTIONS,
);
export const processor = new MessageProcessor([analyticsCatalog], undefined, {
outboundListener: message => {
console.log('Outbound:', message);
},
unifiedOutbound: true,
});
processor.onSurfaceCreated(surface => {
render(html`<a2ui-surface .surface=${surface}></a2ui-surface>`, document.body);
});

If your app targets v0.9.1, pass '0.9' as the catalog version and import from '@a2ui/lit/v0_9', '@a2ui/react/v0_9', '@a2ui/web_core/v0_9', '@a2ui/web_core/v0_9/basic_catalog', or provideA2Ui({useUniversalComponents: true, ...}) from '@a2ui/angular/v0_9'. For agent transport setup, see How to Integrate A2UI into a Client.

When your agent streams a createSurface and updateComponents message pair, the host renderer mounts <a2ui-stat-card> with the resolved properties:

[
{
"version": "1.0",
"createSurface": {
"surfaceId": "main",
"catalogId": "https://example.com/catalogs/analytics/v1/catalog.json"
}
},
{
"version": "1.0",
"updateComponents": {
"surfaceId": "main",
"components": [
{"id": "root", "component": "StatCard", "label": "Monthly revenue", "value": "$12,400"}
]
}
}
]

Resolved property types

@a2ui/lit re-exports A2uiLitElement from @a2ui/web_core/universal, so universal components and @a2ui/lit custom components access resolved schema properties on this.controller.props in the same way:

  • Actions (ActionSchema / Action): resolves to an async () => Promise<void> callback (props.action?.()) that dispatches an agent event or executes a catalog functionCall (see Actions and Functions).
  • Child components (ChildSchema / ComponentId and ChildListSchema / ChildList): resolves to a child reference or array of references. Pass each entry to this.renderNode(ref) inside render() to mount Basic Catalog, universal, or native React and Angular children.
  • Two-way data binding (DynamicStringSchema, DynamicNumberSchema, DynamicBooleanSchema, DynamicStringListSchema, DynamicValueSchema / DynamicValue): generates a props.set<CapitalizedProp>(nextValue) setter (such as props.setValue(e.target.value)) that writes to the bound JSON Pointer (@path in v1.0, path in v0.9.1) in the surface DataModel (see Data Model and Data Binding).
  • Validation checks (z.object({...}).merge(CheckableSchema) / Checkable): evaluates @checks rules (checks in v0.9.1) reactively and populates props.isValid (boolean) and props.validationErrors (string[]). Bind aria-invalid and aria-describedby on the inner input control rather than role="alert" so initial validation checks do not trigger unsolicited screen-reader announcements on mount.

Advanced topics

Light DOM, Shadow DOM, and host CSS theming

Unlike a standard LitElement, A2uiLitElement renders into the Light DOM by default (createRenderRoot() returns this) so the host application’s global stylesheet, design system, and utility classes (such as Tailwind CSS) apply directly inside your component. A2uiLitElement.adoptLightDomStyles() still applies static override styles on connection: it rewrites :host selectors to the custom element’s tag name, prefixes descendant rules with that tag name to prevent style leaks, and adopts the scoped CSSStyleSheet once into the enclosing Document or ShadowRoot.

You can theme the component from the host application using CSS custom properties:

Set custom properties in the enclosing Lit component’s static override styles (or on :root in a global stylesheet):

static override styles = css`
a2ui-stat-card {
--border-color: #3b82f6;
}
`;

If your component requires style encapsulation or native <slot> projection, opt into Shadow DOM by overriding createRenderRoot():

override createRenderRoot() {
return this.attachShadow({mode: 'open'});
}

Writing a universal component without Lit (HTMLElement + GenericBinder)

Lit simplifies templates, but the renderer contract has no Lit dependency. Any class extending HTMLElement and implementing A2uiWebComponentElement works across Lit, React, and Angular:

  1. Extend HTMLElement and implement A2uiWebComponentElement with a context setter accepting ComponentContext from the host renderer.
  2. Instantiate new GenericBinder(context, schema) when connected and subscribe to property updates to mutate the DOM.
  3. Unsubscribe and call binder.dispose() in disconnectedCallback() and before rebinding to a new context.
  4. Export a WebComponentImplementation with your API, tagName, and element constructor.

The example below implements a StatBadgeElement for a StatBadgeApi schema with label, value, and optional children properties, keying cached child DOM elements by ${childId}:${childPath} so repeating template items preserve focus and internal state across data updates:

stat-badge.ts
import {z} from 'zod';
import {ComponentContext, GenericBinder, type ResolveA2uiProps} from '@a2ui/web_core';
import {
type A2uiWebComponentElement,
type ResolvedChildList,
type WebComponentImplementation,
isWebComponentImplementation,
registerUniversalElement,
} from '@a2ui/web_core/universal';
import {StatBadgeApi} from './stat-badge.api.js';
type StatBadgeProps = ResolveA2uiProps<z.infer<typeof StatBadgeApi.schema>>;
export class StatBadgeElement extends HTMLElement implements A2uiWebComponentElement {
private binder?: GenericBinder<StatBadgeProps>;
private subscription?: {unsubscribe(): void};
private currentContext?: ComponentContext;
private readonly labelEl = document.createElement('span');
private readonly childElements = new Map<string, A2uiWebComponentElement>();
get context() {
return this.currentContext;
}
set context(context: ComponentContext | undefined) {
this.currentContext = context;
this.bind();
}
connectedCallback() {
this.bind();
}
disconnectedCallback() {
this.unbind();
}
private bind() {
this.unbind();
if (!this.currentContext || !this.isConnected) return;
this.binder = new GenericBinder(this.currentContext, StatBadgeApi.schema);
this.subscription = this.binder.subscribe(props => this.render(props));
this.render(this.binder.snapshot);
}
private unbind() {
this.subscription?.unsubscribe();
this.binder?.dispose();
this.subscription = undefined;
this.binder = undefined;
}
private render(props: StatBadgeProps) {
const label = typeof props.label === 'string' ? props.label : '';
const value = typeof props.value === 'string' ? props.value : '';
this.labelEl.textContent = `${label}: ${value}`;
this.replaceChildren(this.labelEl, ...this.renderChildren(props.children ?? []));
}
private renderChildren(children: ResolvedChildList): A2uiWebComponentElement[] {
const {surface, path} = this.currentContext!.dataContext;
if (!surface) return [];
const elements: A2uiWebComponentElement[] = [];
for (const childRef of children) {
const childId = typeof childRef === 'string' ? childRef : childRef.id;
const childPath = typeof childRef === 'string' ? path : childRef.basePath;
const childKey = `${childId}:${childPath}`;
const childContext = new ComponentContext(surface, childId, childPath);
const catalog = childContext.componentModel.catalog ?? surface.defaultCatalog;
const impl = catalog?.components.get(childContext.componentModel.type);
if (!impl?.tagName) continue;
if (isWebComponentImplementation(impl)) registerUniversalElement(impl);
let el = this.childElements.get(childKey);
if (!el || el.localName !== impl.tagName) {
el = document.createElement(impl.tagName) as A2uiWebComponentElement;
this.childElements.set(childKey, el);
}
el.context = childContext;
elements.push(el);
}
return elements;
}
}
export const statBadgeComponent: WebComponentImplementation<typeof StatBadgeApi.schema> = {
...StatBadgeApi,
tagName: 'a2ui-stat-badge',
element: StatBadgeElement,
};