glchat-a2ui-react-renderer

GLChat styling and component extensions for @a2ui/react (A2UI v0.9). This package wraps the standard A2UI renderer pipeline with a registered catalog, design tokens, and GLChat-specific UI components.

Overview

| Export | Description | |---|---| | Provider | Owns the MessageProcessor, surface group state, and GLChat catalog | | SurfaceRenderer | Renders one or all active surfaces (requires Provider) | | Design tokens | styles/globals.css, styles/theme-v4.css, tailwind-config.cjs |

Requirements

• React 18+
• Tailwind CSS v3 or v4
• Material Symbols Outlined — required only for string-based Icon components (see Icons)

Installation

npm install glchat-a2ui-react-renderer

Quick start

import { Provider, SurfaceRenderer } from 'glchat-a2ui-react-renderer';
import type { A2UIMessage, ActionPayload } from 'glchat-a2ui-react-renderer';

function App() {
  const messages: A2UIMessage[] = [/* A2UI v0.9 messages from the backend */];

  const handleAction = (action: ActionPayload) => {
    // { name, surfaceId, sourceComponentId, timestamp, context }
    console.log('Action:', action);
  };

  return (
    <Provider messages={messages} onAction={handleAction}>
      <SurfaceRenderer />
    </Provider>
  );
}

Configuration notes:

• SurfaceRenderer accepts an optional surfaceId to render a single surface.
• The fallback prop controls the loading UI (default: "Waiting for agent...").
• Provider configures markdown rendering for Text via @a2ui/markdown-it.
• onAction receives v0.9 A2uiClientAction payloads from interactive components.

Icons

The upstream Icon component renders Material Symbols Outlined when name is a string. This package does not bundle the font; consumers must load it in the application shell:

<link
  href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined&display=swap"
  rel="stylesheet"
/>

Alternatively, import it in global CSS before other stylesheets:

@import url('https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined&display=swap');

Icons specified with an SVG path object ({ "svgPath": "..." }) render as inline SVG and do not require the font.

Typography

The default typeface is Inter, exposed through the --font-sans token. This package does not @import Google Fonts from globals.css to remain compatible with Next.js stylesheet merging.

Consumers may use an existing application font by overriding the token on .a2ui-surface:

.a2ui-surface {
  --font-sans: var(--your-app-font);
}

To adopt Inter explicitly:

• Next.js: configure next/font/google with variable: '--font-sans' on the root element.
• Plain CSS: @import Inter before globals.css.

GLChat catalog

Provider registers the extended catalog automatically. All other components use the upstream A2UI v0.9 basic catalog.

| Component | Role | |---|---| | Button | Override — GLChat styling; adds destructive variant | | ChoicePicker | Override — select, multi-select, and checkbox list | | TagInput | Extension | | Timeout | Extension |

See Custom components to register additional components on top of this catalog. Component schemas are documented in json/README.md.

Custom components (Optional)

Custom components are defined with a Zod schema and a React renderer, then registered in a Catalog passed to Provider.

1. Define the component API

import { z } from 'zod';
import {
  createComponentImplementation,
  DynamicStringSchema,
  AccessibilityAttributesSchema,
} from 'glchat-a2ui-react-renderer';

export const BadgeApi = {
  name: 'Badge',
  schema: z
    .object({
      accessibility: AccessibilityAttributesSchema.optional(),
      weight: z.number().optional(),
      label: DynamicStringSchema.describe('Text shown in the badge.'),
    })
    .strict()
    .describe('A simple label badge.'),
};

2. Implement the renderer

createComponentImplementation binds resolved props from the data model (e.g. props.label, props.action, props.value, props.setValue for interactive fields):

export const BadgeComponent = createComponentImplementation(BadgeApi, ({ props }) => (
  <span className="inline-flex rounded-md bg-muted px-2 py-0.5 text-sm">{props.label}</span>
));

For child components, use buildChild:

createComponentImplementation(MyApi, ({ props, buildChild }) => (
  <div>{props.child ? buildChild(props.child) : null}</div>
);

3. Build a catalog

Start from createGlchatCatalog() and append the new component. Reuse GLCHAT_CATALOG_ID so existing createSurface messages remain valid:

import {
  Catalog,
  createGlchatCatalog,
  GLCHAT_CATALOG_ID,
} from 'glchat-a2ui-react-renderer';

const glchat = createGlchatCatalog();
const catalog = new Catalog(
  GLCHAT_CATALOG_ID,
  [...glchat.components.values(), BadgeComponent],
  [...glchat.functions.values()],
);

4. Pass the catalog to Provider

<Provider messages={messages} catalog={catalog} onAction={handleAction}>
  <SurfaceRenderer />
</Provider>

Custom layout

For explicit control over surface layout, use useSurfaceGroup, useSurfaces, and A2uiSurface instead of SurfaceRenderer:

import { useSurfaceGroup, useSurfaces, A2uiSurface } from 'glchat-a2ui-react-renderer';

function CustomLayout() {
  const model = useSurfaceGroup();
  const surfaces = useSurfaces(model);

  if (surfaces.length === 0) return <Spinner />;

  return surfaces.map((surface) => (
    <div key={surface.id} className="a2ui-surface">
      <A2uiSurface surface={surface} />
    </div>
  ));
}

Tailwind setup

Tailwind v4

Add the following to the application CSS entry point:

@import "tailwindcss";

/* Load design tokens */
@import "glchat-a2ui-react-renderer/styles/globals.css";

/* Register tokens with Tailwind */
@import "glchat-a2ui-react-renderer/styles/theme-v4.css";

/* Optional: ensure Tailwind scans this package */
@source "../node_modules/glchat-a2ui-react-renderer";

Tailwind v3

Use the provided preset and include the package in content.

const glchatPreset = require('glchat-a2ui-react-renderer/tailwind-config.cjs');

module.exports = {
  presets: [glchatPreset],
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    './app/**/*.{js,ts,jsx,tsx}',
    './node_modules/glchat-a2ui-react-renderer/dist/**/*.{js,jsx,ts,tsx}',
  ],
};

Import styles/globals.css before the @tailwind directives.

Theming

Components are styled with CSS custom properties. Override :root tokens in application CSS after importing globals.css:

:root {
  --primary: 220 90% 45%;
  --background: 0 0% 99%;
}

.dark {
  --primary: 220 70% 50%;
}

JSON schemas

Published for agent catalog registration and reference:

| File | Description | |---|---| | json/glchat_standard_catalog_definition.json | GLChat catalog definition | | json/a2ui-sample-messages.json | Sample message sequence |

Public API

Components and hooks

| Export | Description | |---|---| | Provider | Message processor, surface group, and GLChat catalog | | SurfaceRenderer | Renders one or all surfaces | | useSurfaceGroup | Subscribes to the surface group model from Provider | | useSurfaces | Returns active surfaces from a surface group model |

Types

| Export | Description | |---|---| | ProviderProps | Props for Provider | | SurfaceRendererProps | Props for SurfaceRenderer | | A2UIMessage | Server-to-client message type | | ActionPayload | Normalized action payload passed to onAction | | ActionHandler | (action: ActionPayload) => void | | MessageErrorHandler | (error: Error) => void | | ReactComponentImplementation | Catalog component implementation type | | ReactA2uiComponentProps | Props passed to custom component renderers | | ComponentApi | Zod schema definition for a catalog component | | A2uiMessage | Upstream message type (@a2ui/web_core) | | A2uiClientAction | Upstream client action type (@a2ui/web_core) |

Catalog (GLChat)

| Export | Description | |---|---| | createGlchatCatalog | Builds the GLChat extended v0.9 catalog | | GLCHAT_CATALOG_ID | Catalog URI for createSurface messages | | GlchatButtonComponent | GLChat Button implementation | | GlchatButtonApi | Extended Button schema (includes destructive variant) | | GlchatChoicePickerComponent | GLChat ChoicePicker implementation | | GlchatTagInputComponent | TagInput implementation | | TagInputApi | TagInput schema | | GlchatTimeoutComponent | Timeout implementation | | TimeoutApi | Timeout schema |

Re-exports (@a2ui/react v0.9)

| Export | Description | |---|---| | A2uiSurface | Low-level surface renderer | | createComponentImplementation | Factory for catalog-bound components | | createBinderlessComponentImplementation | Factory for components without data binding | | MarkdownContext | Markdown renderer context | | useMarkdownRenderer | Hook for custom markdown rendering |

Re-exports (@a2ui/web_core v0.9)

| Export | Description | |---|---| | Catalog | Catalog container (components + functions) | | MessageProcessor | Processes A2UI message streams | | SurfaceModel | Single-surface state model | | SurfaceGroupModel | Multi-surface state model | | ComponentIdSchema | Component ID validator | | ChildListSchema | Child list validator | | ActionSchema | Action validator | | DynamicStringSchema | Dynamic string value validator | | DynamicNumberSchema | Dynamic number value validator | | DynamicBooleanSchema | Dynamic boolean value validator | | DynamicStringListSchema | Dynamic string list validator | | DynamicValueSchema | Dynamic value validator | | CheckableSchema | Validation rules validator | | AccessibilityAttributesSchema | Accessibility attributes validator |

Package assets

| Export | Description | |---|---| | styles/globals.css | Design tokens and A2UI surface overrides | | styles/theme-v4.css | Tailwind v4 theme bridge | | tailwind-config.cjs | Tailwind v3 preset | | json/glchat_standard_catalog_definition.json | GLChat catalog JSON | | json/a2ui-sample-messages.json | Sample messages JSON |

Refer to A2UI renderer documentation for upstream API details.

License

MIT