generating-flutter-ui

Flutter Generative UI (GenUI) Best Practices

Goal

Implement a dynamic user interface generated by AI using the genui package. This is the recommended approach when an application needs to build reactive screens or components directly from AI responses without hardcoding the layout.

Instructions

The genui package orchestrates a conversational loop between the user, the AI (via ContentGenerator), and the Flutter UI (via A2uiMessageProcessor and DataModel).

1. Project Setup

Add the necessary packages to your pubspec.yaml:

flutter pub add genui
# For Gemini integration via Firebase:
flutter pub add genui_firebase_ai

If targeting macOS/iOS, enable outbound network requests in entitlements:

<key>com.apple.security.network.client</key>
<true/>

2. Core Integration Structure

To connect your Flutter application to the AI agent, you need to instantiate three main components:

1. A2uiMessageProcessor: Handles the UI side, translating AI messages into UI actions. Supply it with a Catalog of widgets the AI is allowed to use.
2. ContentGenerator: Handles communication with the AI. Supply it with system instructions and tools.
3. GenUiConversation: The facade coordinating the processor and generator.

Example Setup in a StatefulWidget:

import 'package:flutter/material.dart';
import 'package:genui/genui.dart';
import 'package:genui_firebase_ai/genui_firebase_ai.dart';

class GenUIPage extends StatefulWidget {
  const GenUIPage({super.key});

  @override
  State<GenUIPage> createState() => _GenUIPageState();
}

class _GenUIPageState extends State<GenUIPage> {
  late final A2uiMessageProcessor _a2uiMessageProcessor;
  late final GenUiConversation _genUiConversation;

  @override
  void initState() {
    super.initState();

    // 1. Initialize Message Processor with predefined catalog widgets
    _a2uiMessageProcessor = A2uiMessageProcessor(
      catalogs: [CoreCatalogItems.asCatalog()],
    );

    // 2. Initialize Content Generator (e.g., Firebase AI / Gemini)
    final contentGenerator = FirebaseAiContentGenerator(
      catalog: CoreCatalogItems.asCatalog(),
      systemInstruction: '''
        You are an AI assistant. You must generate UI by responding with JSON
        matching the provided widget schemas. Always output valid UI structures.
      ''',
      tools: _a2uiMessageProcessor.getTools(),
    );

    // 3. Orchestrate the Conversation
    _genUiConversation = GenUiConversation(
      a2uiMessageProcessor: _a2uiMessageProcessor,
      contentGenerator: contentGenerator,
      // Implement your handlers for rendering generated surfaces
      onSurfaceAdded: (surfaceId) { /* Handle surface creation */ },
      onSurfaceDeleted: (surfaceId) { /* Handle surface deletion */ },
      onTextResponse: (text) { /* Optional: show text explicitly */ },
      onError: (error) { /* Handle generation errors */ },
    );
  }

  @override
  void dispose() {
    _genUiConversation.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    // UI Implementation interacting with _genUiConversation.sendRequest()
    return const Scaffold();
  }
}