GenUI SDK (A2UI) integration for
fl_select: exposes fl_select
components as CatalogItems so conversational AI agents can render real,
interactive selection UIs inside chat surfaces — and receive the user's
selections back as structured query data.
agent ──JSON payload──▶ Select (fl_select UI) ──selection──▶ Map<String, List<String>>
How it works
-
You register
FlSelectCatalogItems.asCatalog()(or.all) with your GenUISurfaceControlleralongside the basic catalog. -
Your agent's system prompt includes
FlSelectCatalogItems.systemPromptFragment, which teaches it theSelectvocabulary. -
When the user needs to pick values, the agent emits a
Selectpayload — adelegate(list / grid / wrap / cascading / tabNav / sideNav / expandable) plus anentriestree authored in theSelectEntryCodecJSON format. The shape has to match the delegate: flat nodes forlist/grid/wrap, acategorytree forcascading/tabNav/sideNav/expandable. A category picks how its own children render through itslayout:list/grid/chip/counter/rangerender one level,cascadingrenders one column per level and drills into nested children.Optional top-level fields tune the whole panel:
selectionMode(single/multiple),search(boolean),defaultLayout(a layout object used by categories without their ownlayout, fortabNav/sideNav/expandable) andisScrollable(tabNav/sideNav/cascading). LeaveisScrollableout andtabNavscrolls on its own when its category names do not fit the width. -
The user interacts with a real fl_select component; selections are written back to the GenUI data model at
<id>.valueas aMap<String, List<String>>(same shape as fl_select'stoQueryMap), ready for the next agent turn or your query layer.
Invalid agent payloads render an inline error card instead of crashing.
Agent Skills
This package ships an agent skill for the Dart Skills CLI at skills/fl-select-genui-code-generation, so AI coding agents (Claude Code, Cursor, Codex, Windsurf, GitHub Copilot, etc.) author Select payloads correctly — catalog registration, the SelectEntryCodec entry-tree format, selection write-back, and the SelectEntrySchema JSON Schema.
It is discovered automatically in any project that depends on fl_select_genui. Run this from the project root (the CLI resolves skills from that project's dependency tree):
# install every discovered skill without prompting
dart run skills@ get --all
# or pick interactively / target one package
dart run skills@ get
dart run skills@ get --package fl_select_genui
Usage
import 'package:fl_select_genui/fl_select_genui.dart';
import 'package:genui/genui.dart';
final controller = SurfaceController(
catalogs: [
BasicCatalogItems.asCatalog().copyWith(
newItems: FlSelectCatalogItems.all,
),
],
);
// System prompt:
FlSelectCatalogItems.systemPromptFragment;
See example/ for an end-to-end example of the payload →
render → write-back loop.
Entry tree format
{"type": "category", "id": "price", "name": "Price", "children": [
{"type": "any", "name": "Any"},
{"type": "range", "id": "0-100", "name": "$0 - $100", "min": 0, "max": 100},
{"type": "custom", "name": "Custom", "min": 0, "max": 1000}
]}
Node types: category (group, optional selectionMode / layout and
header/footer chip rows with their own headerSelectionMode /
footerSelectionMode), text (option or sub-branch), range (slider),
any (reset sentinel), custom (user-typed range). See SelectEntrySchema
for the generated JSON Schema and FlSelectCatalogItems.systemPromptFragment
for the agent-facing documentation.
Libraries
- fl_select_genui
- GenUI SDK integration for fl_select.