The GenUI Widget Catalog: Teaching an LLM Your App's Widget Vocabulary
How CatalogItem, JSON schemas, and the DataModel define which Flutter widgets the genui package lets an AI generate.
Published on • October 20, 2026
AI Assistant

The genui package (published by labs.flutter.dev, currently at 0.10.4 and flagged alpha on docs.flutter.dev) doesn’t let a model emit arbitrary Flutter code. It lets a model pick from a catalog you define: a fixed vocabulary of named widgets, each with a data schema and a builder. That constraint is the feature. This post walks through the catalog API as it actually exists today.
What a catalog really is
A Catalog is a collection of CatalogItems. Each item gives the AI three things:
- A name — the string the model references in its A2UI output (for example
RiddleCard). - A data schema — a JSON schema describing the properties the widget accepts, built with the
json_schema_builderpackage. - A
widgetBuilder— a function that takes a build context and returns the real Flutter widget tree.
The SurfaceController accepts multiple catalogs, so you can group widgets logically (core primitives plus your domain-specific ones). Out of the box you start with the bundled core set:
_controller = SurfaceController(
catalogs: [CoreCatalogItems.asCatalog()],
);
The core catalog covers the basics — the README shows direct examples of Text (with a hint property like h1) and Image (with url and hints like mediumFeature). Everything beyond that is yours to add.
Defining a custom item
Add json_schema_builder first:
flutter pub add json_schema_builder
Then declare the schema. The schema is the contract the model validates against before it ever emits a message:
import 'package:json_schema_builder/json_schema_builder.dart';
import 'package:flutter/material.dart';
import 'package:genui/genui.dart';
final _schema = S.object(
properties: {
'question': S.string(description: 'The question part of a riddle.'),
'answer': S.string(description: 'The answer part of a riddle.'),
},
required: ['question', 'answer'],
);
Descriptions matter here — they’re what the model reads to decide when the item applies. A vague description produces a widget the model reaches for at the wrong moment.
The CatalogItem combines name, schema, and builder:
final riddleCard = CatalogItem(
name: 'RiddleCard',
dataSchema: _schema,
widgetBuilder: (context) {
final questionNotifier = context.dataContext.subscribeToString(
context.data['question'] as Map<String, Object?>?,
);
final answerNotifier = context.dataContext.subscribeToString(
context.data['answer'] as Map<String, Object?>?,
);
return ValueListenableBuilder<String?>(
valueListenable: questionNotifier,
builder: (context, question, _) {
return ValueListenableBuilder<String?>(
valueListenable: answerNotifier,
builder: (context, answer, _) {
return Container(
constraints: const BoxConstraints(maxWidth: 400),
decoration: BoxDecoration(border: Border.all()),
padding: const EdgeInsets.all(16),
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
Text(
question ?? '',
style: Theme.of(context).textTheme.headlineMedium,
),
const SizedBox(height: 8.0),
Text(
answer ?? '',
style: Theme.of(context).textTheme.headlineSmall,
),
],
),
);
},
);
},
);
},
);
Notice that the builder doesn’t receive data directly. It subscribes through context.dataContext, which is the bridge to the DataModel.
Registering it with the SurfaceController
Combine your item with the core catalog using copyWith:
_controller = SurfaceController(
catalogs: [CoreCatalogItems.asCatalog().copyWith([riddleCard])],
);
The SurfaceController is the runtime engine: it processes A2uiMessages (createSurface, updateComponents, updateDataModel, deleteSurface), owns the DataModel, and broadcasts updates so Surface widgets listening to a surface ID rebuild.
The catalog is a prompt, not just code
Registering the item isn’t enough. The model has to know the name exists and when to use it. The package README is explicit: you need prompt engineering — one-shot or few-shot examples in the system instruction — that names RiddleCard and shows when it applies. Practically, that means your system prompt should carry a short catalog manifest:
Widgets you may use:
- RiddleCard: use for a riddle with a question and an answer.
Example: {"RiddleCard": {"question": "What has keys...", "answer": "A piano"}}
- Text, Image, ... (core catalog)
Treat the schema as validation and the prompt as discovery. Schema alone stops malformed output; prompting alone doesn’t stop the model from inventing widget names your catalog will reject.
Data binding is where the reactivity lives
Properties in the AI’s output are either literal values or path objects that bind into the DataModel. When the user types into a TextField bound to /user/name, the model updates at that path, and every widget subscribed to it rebuilds — nothing else does. The DataModel is a centralized, observable store, so instead of wiring setState chains across generated widgets, you get per-path invalidation for free.
That also makes the interaction loop high-bandwidth: input widgets write state locally, actions (like button clicks) get captured by the SurfaceController and emitted back to the Conversation as context for the next model turn. You can see this loop in the package README’s architecture diagram.
Practical guidance
- Keep item count small. Every item is prompt surface area. Ten well-described items beat forty vague ones.
- Design schemas for the model, builders for the user. The schema should make invalid states unrepresentable (
requiredfields, enums); the builder should handle nulls defensively anyway. - Build in the catalog, not in the message. If a widget needs new behavior, add a
CatalogItem— never let the model emit arbitrary widget trees. - Log the traffic. The README shows
configureLogging(level: Level.ALL)frompackage:loggingto watch exactly what the model requested versus what your catalog resolved.
The catalog is the boundary between “the AI generates UI” and “the AI generates your UI.” Spend the time there.