A2UI integration for fl_select,
built on the A2UI Dart SDKs a2ui_core
and a2ui_flutter: exposes fl_select
components as catalog components (ComponentImplementations) 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, added to the basic catalog) with your A2UIMessageProcessor. -
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.A
gridthe agent leaves unshaped —{"kind": "grid", "crossAxisCount": 2}— gets the catalog's compact tiles (3:1, 10px apart) rather thanfl_select's square, touching defaults, which are meant for icon grids;tabNavfalls back to the same shape when a category has no layout of its own, and a missing or unusablecrossAxisCountbecomes 3 columns. SetchildAspectRatio/mainAxisSpacing/crossAxisSpacingin the layout to keep a different shape.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.Like the basic components, a
Selectalso accepts A2UI's commonweight(its share of aRow/Columnmain axis) andaccessibility(label/descriptionfor screen readers) properties. -
The user interacts with a real fl_select component; selections are written back to the surface's 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.
The MessageProcessor rejects a payload that does not match the Select
schema (a wrong type, an unknown delegate token, empty entries, or a
property the schema does not declare) and reports it on
processor.model.onError. Other 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:a2ui_core/a2ui_core.dart';
import 'package:a2ui_flutter/a2ui_flutter.dart';
import 'package:a2ui_flutter/v0_9/basic_catalog.dart' as v0_9;
import 'package:fl_select_genui/fl_select_genui.dart';
final processor = MessageProcessor<ComponentImplementation>(
catalogs: [
v0_9.basicCatalog().copyWith(
components: [...v0_9.BasicComponents.all, ...FlSelectCatalogItems.all],
),
],
);
// Pass the agent's A2UI messages to processor.processMessages(...) and render
// each surface it creates with A2uiSurface(surface: surface).
// 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.
The top level is either all category nodes or a flat list of leaves — never
both. A non-category entry beside a category is invalid (a category tree
needs every top-level entry to be a category, which is how fl_select renders
its navigation) and renders the error card.
Libraries
- fl_select_genui
- A2UI integration for fl_select.