{"id":23353404,"url":"https://github.com/hooshyar/flutter_gen_ai_chat_ui","last_synced_at":"2025-10-28T22:30:49.626Z","repository":{"id":266308335,"uuid":"897978735","full_name":"hooshyar/flutter_gen_ai_chat_ui","owner":"hooshyar","description":"A modern, customizable chat UI package for Flutter applications, optimized for AI interactions.","archived":false,"fork":false,"pushed_at":"2025-02-11T16:46:11.000Z","size":1865,"stargazers_count":6,"open_issues_count":1,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-11T17:44:47.651Z","etag":null,"topics":["ai","chatbot","chatgpt","flutter","genai","genai-chatbot","ui"],"latest_commit_sha":null,"homepage":"https://www.dilacode.com","language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hooshyar.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-03T15:18:07.000Z","updated_at":"2025-02-11T16:46:15.000Z","dependencies_parsed_at":null,"dependency_job_id":"e454eb1b-60b7-4e45-8aa3-8be88ccaa676","html_url":"https://github.com/hooshyar/flutter_gen_ai_chat_ui","commit_stats":null,"previous_names":["hooshyar/flutter_gen_ai_chat_ui"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hooshyar%2Fflutter_gen_ai_chat_ui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hooshyar%2Fflutter_gen_ai_chat_ui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hooshyar%2Fflutter_gen_ai_chat_ui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hooshyar%2Fflutter_gen_ai_chat_ui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hooshyar","download_url":"https://codeload.github.com/hooshyar/flutter_gen_ai_chat_ui/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238734085,"owners_count":19521557,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","chatbot","chatgpt","flutter","genai","genai-chatbot","ui"],"created_at":"2024-12-21T09:13:07.003Z","updated_at":"2025-10-28T22:30:49.619Z","avatar_url":"https://github.com/hooshyar.png","language":"Dart","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Flutter Gen AI Chat UI\n\n[![pub package](https://img.shields.io/pub/v/flutter_gen_ai_chat_ui.svg)](https://pub.dev/packages/flutter_gen_ai_chat_ui)\n[![pub likes](https://img.shields.io/pub/likes/flutter_gen_ai_chat_ui)](https://pub.dev/packages/flutter_gen_ai_chat_ui/score)\n[![pub points](https://img.shields.io/pub/points/flutter_gen_ai_chat_ui)](https://pub.dev/packages/flutter_gen_ai_chat_ui/score)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Flutter](https://img.shields.io/badge/Flutter-3.7%2B-blue.svg)](https://flutter.dev)\n[![Platform](https://img.shields.io/badge/platform-android%20%7C%20ios%20%7C%20web%20%7C%20windows%20%7C%20macos%20%7C%20linux-lightgrey.svg)](https://pub.dev/packages/flutter_gen_ai_chat_ui)\n[![GitHub stars](https://img.shields.io/github/stars/hooshyar/flutter_gen_ai_chat_ui.svg?style=flat\u0026logo=github\u0026colorB=deeppink\u0026label=stars)](https://github.com/hooshyar/flutter_gen_ai_chat_ui)\n[![GitHub issues](https://img.shields.io/github/issues/hooshyar/flutter_gen_ai_chat_ui.svg)](https://github.com/hooshyar/flutter_gen_ai_chat_ui/issues)\n\nA modern, high-performance Flutter chat UI kit for building beautiful messaging interfaces. Features streaming text animations, markdown support, file attachments, and extensive customization options. Perfect for AI assistants, customer support, team chat, social messaging, and any conversational application.\n\n**🚀 Production Ready** | **📱 Cross-Platform** | **⚡ High Performance** | **🎨 Fully Customizable**\n\n## Table of Contents\n- [Features](#features)\n- [Performance \u0026 Features](#-performance--features)\n- [Installation](#installation)\n- [Quick Start](#basic-usage)\n- [Live Examples](#-live-examples)\n- [Configuration Options](#configuration-options)\n- [AI Actions System](#-ai-actions-system)\n- [Advanced Features](#advanced-features)\n- [Showcase](#-showcase)\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003cimg src=\"https://raw.githubusercontent.com/hooshyar/flutter_gen_ai_chat_ui/main/screenshots/detailed_dark.png\" alt=\"Dark Mode\" width=\"300px\"\u003e\n      \u003cbr\u003e\n      \u003cem\u003eDark Mode\u003c/em\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003cimg src=\"https://raw.githubusercontent.com/hooshyar/flutter_gen_ai_chat_ui/main/screenshots/detailed.gif\" alt=\"Chat Demo\" width=\"300px\"\u003e\n      \u003cbr\u003e\n      \u003cem\u003eChat Demo\u003c/em\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n## Features\n\n### Core Features\n- 🎨 Dark/light mode with adaptive theming\n- 💫 Word-by-word streaming with animations (like ChatGPT and Claude)\n- 📝 Enhanced markdown support with code highlighting for technical content\n- 🎤 Optional speech-to-text integration\n- 📱 Responsive layout with customizable width\n- 🌐 RTL language support for global applications\n- ⚡ High performance message handling for large conversations\n- 📊 Improved pagination support for message history\n\n### AI-Specific Features\n- 👋 Customizable welcome message similar to ChatGPT and other AI assistants\n- ❓ Example questions component for user guidance\n- 💬 Persistent example questions for better user experience\n- 🔄 AI typing indicators like modern chatbot interfaces\n- 📜 Streaming markdown rendering for code and rich content\n\n### 🚀 **NEW: AI Actions System** \n- ⚡ **Function Calling Support** - AI can execute predefined actions with parameters\n- 🎨 **Generative UI** - Actions render custom widgets showing execution status\n- ✋ **Human-in-the-Loop** - Automatic confirmation dialogs for sensitive operations\n- 📊 **Real-time Status** - Live updates of action execution progress with animations\n- 🛡️ **Type-Safe Parameters** - Full validation system with custom validators\n- 🎯 **Event Streaming** - Track action lifecycle with comprehensive event system\n- 🔧 **Error Handling** - Rich error management with user-friendly feedback\n\n### UI Components\n- 💬 Customizable message bubbles with modern design options\n- 🎨 **Custom Bubble Builder** for complete message styling control\n- ⌨️ Multiple input field styles (minimal, glassmorphic, custom)\n- 🔄 Loading indicators with shimmer effects\n- ⬇️ Smart scroll management for chat history\n- 🎨 Enhanced theme customization to match your brand\n- 📝 Better code block styling for developers\n\n## ⚡ Performance \u0026 Features\n\n### Key Capabilities\n- **✨ Unique Streaming Text**: Word-by-word animations like ChatGPT and Claude\n- **📁 Complete File Support**: Multi-format attachments (images, documents, videos)\n- **📝 Advanced Markdown**: Full support with syntax highlighting for code blocks\n- **🚀 High Performance**: Optimized for large conversations (10K+ messages)\n- **🎨 Extensive Theming**: Complete customization to match your brand\n- **📱 Cross-Platform**: Works on all Flutter-supported platforms\n- **🔗 Backend Agnostic**: Compatible with any API or service\n- **⚡ Real-time Ready**: Built-in support for live updates\n\n### Performance Benchmarks\n- **Message Rendering**: 60 FPS with 1000+ messages\n- **Memory Efficiency**: Optimized for large conversations\n- **Startup Time**: \u003c100ms initialization\n- **Streaming Speed**: Configurable 10-100ms per word\n\n## 🌟 Works Great With\n- **AI Services**: OpenAI, Anthropic Claude, Google Gemini, Llama, Mistral\n- **Backends**: Firebase, Supabase, REST APIs, WebSockets, GraphQL\n- **Use Cases**: Customer support, AI assistants, team chat, social messaging\n- **Industries**: SaaS, E-commerce, Healthcare, Education, Gaming\n\n## Installation\n\nAdd this to your package's pubspec.yaml file:\n\n```yaml\ndependencies:\n  flutter_gen_ai_chat_ui: ^2.4.2\n```\n\nThen run:\n\n```bash\nflutter pub get\n```\n\n## Why Choose This Package?\n\n✅ **Superior Performance**: Optimized for large conversations with efficient message rendering  \n✅ **Modern UI**: Beautiful, customizable interfaces that match current design trends  \n✅ **Streaming Text**: Smooth word-by-word animations like ChatGPT and Claude  \n✅ **File Support**: Complete file attachment system with image, document, and media support  \n✅ **Production Ready**: Stable API with comprehensive testing and documentation  \n✅ **Framework Agnostic**: Works with any backend - REST APIs, WebSockets, Firebase, Supabase\n\n## 🎮 Live Examples\n\nExplore all features with our comprehensive example app:\n- **Basic Chat**: Simple ChatGPT-style interface\n- **Streaming Text**: Real-time word-by-word animations  \n- **File Attachments**: Upload images, documents, videos\n- **Custom Themes**: Light, dark, and glassmorphic styles\n- **Advanced Features**: Scroll behavior, markdown, code highlighting\n\nTo run the example app:\n```bash\ncd example/\nflutter run\n```\n\n## Quick Start\n\n```dart\nimport 'package:flutter_gen_ai_chat_ui/flutter_gen_ai_chat_ui.dart';\n\nclass ChatScreen extends StatefulWidget {\n  @override\n  _ChatScreenState createState() =\u003e _ChatScreenState();\n}\n\nclass _ChatScreenState extends State\u003cChatScreen\u003e {\n  final _controller = ChatMessagesController();\n  final _currentUser = ChatUser(id: 'user', firstName: 'User');\n  final _aiUser = ChatUser(id: 'ai', firstName: 'AI Assistant');\n  bool _isLoading = false;\n\n  @override\n  Widget build(BuildContext context) {\n    return Scaffold(\n      appBar: AppBar(title: Text('AI Chat')),\n      body: AiChatWidget(\n        // Required parameters\n        currentUser: _currentUser,\n        aiUser: _aiUser,\n        controller: _controller,\n        onSendMessage: _handleSendMessage,\n        \n        // Optional parameters\n        loadingConfig: LoadingConfig(isLoading: _isLoading),\n        inputOptions: InputOptions(\n          hintText: 'Ask me anything...',\n          sendOnEnter: true,\n        ),\n        welcomeMessageConfig: WelcomeMessageConfig(\n          title: 'Welcome to AI Chat',\n          questionsSectionTitle: 'Try asking me:',\n        ),\n        exampleQuestions: [\n          ExampleQuestion(question: \"What can you help me with?\"),\n          ExampleQuestion(question: \"Tell me about your features\"),\n        ],\n      ),\n    );\n  }\n\n  Future\u003cvoid\u003e _handleSendMessage(ChatMessage message) async {\n    setState(() =\u003e _isLoading = true);\n    \n    try {\n      // Your AI service logic here\n      await Future.delayed(Duration(seconds: 1)); // Simulating API call\n      \n      // Add AI response\n      _controller.addMessage(ChatMessage(\n        text: \"This is a response to: ${message.text}\",\n        user: _aiUser,\n        createdAt: DateTime.now(),\n      ));\n    } finally {\n      setState(() =\u003e _isLoading = false);\n    }\n  }\n}\n```\n\n## Configuration Options\n\n### AiChatWidget Parameters\n\n#### Required Parameters\n```dart\nAiChatWidget(\n  // Required parameters\n  currentUser: ChatUser(...),  // The current user\n  aiUser: ChatUser(...),       // The AI assistant\n  controller: ChatMessagesController(),  // Message controller\n  onSendMessage: (message) {   // Message handler\n    // Handle user messages here\n  },\n  \n  // ... optional parameters\n)\n```\n\n#### Optional Parameters\n\n```dart\nAiChatWidget(\n  // ... required parameters\n  \n  // Message display options\n  messages: [],                // Optional list of messages (if not using controller)\n  messageOptions: MessageOptions(...),  // Message bubble styling\n  messageListOptions: MessageListOptions(...),  // Message list behavior\n  \n  // Input field customization\n  inputOptions: InputOptions(...),  // Input field styling and behavior\n  readOnly: false,             // Whether the chat is read-only\n  \n  // AI-specific features\n  exampleQuestions: [          // Suggested questions for users\n    ExampleQuestion(question: 'What is AI?'),\n  ],\n  persistentExampleQuestions: true,  // Keep questions visible after welcome\n  enableAnimation: true,       // Enable message animations\n  enableMarkdownStreaming: true,  // Enable streaming text (FIXED in v2.4.2+)\n  streamingWordByWord: false,     // Control word-by-word vs character animation  \n  streamingDuration: Duration(milliseconds: 30),  // Stream speed\n  welcomeMessageConfig: WelcomeMessageConfig(...),  // Welcome message styling\n  \n  // Loading states\n  loadingConfig: LoadingConfig(  // Loading configuration\n    isLoading: false,\n    showCenteredIndicator: true,\n  ),\n  \n  // Pagination\n  paginationConfig: PaginationConfig(  // Pagination configuration\n    enabled: true,\n    reverseOrder: true,  // Newest messages at bottom\n  ),\n  \n  // Layout\n  maxWidth: 800,             // Maximum width\n  padding: EdgeInsets.all(16),  // Overall padding\n  \n  // Scroll behavior\n  scrollBehaviorConfig: ScrollBehaviorConfig(\n    // Control auto-scrolling behavior\n    autoScrollBehavior: AutoScrollBehavior.onUserMessageOnly,\n    // Scroll to first message of a response instead of the last (for long responses)\n    scrollToFirstResponseMessage: true,\n  ),\n  \n  // Custom bubble builder for complete styling control\n  customBubbleBuilder: (context, message, isCurrentUser, defaultBubble) {\n    // Return your custom bubble widget\n    return Container(\n      decoration: BoxDecoration(\n        borderRadius: BorderRadius.circular(12),\n        boxShadow: [\n          BoxShadow(\n            color: Colors.black.withOpacity(0.1),\n            blurRadius: 4,\n            offset: Offset(0, 2),\n          ),\n        ],\n      ),\n      child: defaultBubble, // Or create completely custom UI\n    );\n  },\n)\n```\n\n### Input Field Customization\n\nThe package offers multiple ways to style the input field:\n\n#### Default Input\n\n```dart\nInputOptions(\n  // Basic properties\n  sendOnEnter: true,\n  \n  // Focus behavior (NEW in v2.4.2+)\n  autofocus: true,          // Automatically focus the input field\n  focusNode: myFocusNode,   // Custom focus node for external control\n  \n  // Styling\n  textStyle: TextStyle(...),\n  decoration: InputDecoration(...),\n)\n```\n\n#### Minimal Input\n\n```dart\nInputOptions.minimal(\n  hintText: 'Ask a question...',\n  textColor: Colors.black,\n  hintColor: Colors.grey,\n  backgroundColor: Colors.white,\n  borderRadius: 24.0,\n  autofocus: true,        // Available in factory constructors too\n  focusNode: myFocusNode, // Custom focus node support\n)\n```\n\n#### Glassmorphic (Frosted Glass) Input\n\n```dart\nInputOptions.glassmorphic(\n  colors: [Colors.blue.withOpacityCompat(0.2), Colors.purple.withOpacityCompat(0.2)],\n  borderRadius: 24.0,\n  blurStrength: 10.0,\n  hintText: 'Ask me anything...',\n  textColor: Colors.white,\n  autofocus: false,       // Control autofocus behavior\n  focusNode: myFocusNode, // Optional custom focus node\n)\n```\n\n#### Custom Input\n\n```dart\nInputOptions.custom(\n  decoration: yourCustomDecoration,\n  textStyle: yourCustomTextStyle,\n  sendButtonBuilder: (onSend) =\u003e CustomSendButton(onSend: onSend),\n)\n```\n\n#### Always-Visible Send Button Without Focus Issues (version 2.0.4+)\n\nThe send button is now hardcoded to always be visible by design, regardless of text content. This removes the need for an explicit setting and ensures a consistent experience across the package.\n\nBy default:\n- The send button is always shown regardless of text input\n- Focus is maintained when tapping outside the input field\n- The keyboard's send button is disabled by default to prevent focus issues\n\n```dart\n// Configure input options to ensure a consistent typing experience\nInputOptions(\n  // Prevent losing focus when tapping outside\n  unfocusOnTapOutside: false,\n  \n  // Use newline for Enter key to prevent keyboard focus issues\n  textInputAction: TextInputAction.newline,\n)\n```\n\n### Scroll Behavior Configuration\n\nControl how the chat widget scrolls when new messages are added:\n\n```dart\n// Default configuration with manual parameters\nScrollBehaviorConfig(\n  // When to auto-scroll (one of: always, onNewMessage, onUserMessageOnly, never)\n  autoScrollBehavior: AutoScrollBehavior.onUserMessageOnly,\n  \n  // Fix for long responses: scroll to first message of response instead of the last message\n  // This prevents the top part of long AI responses from being pushed out of view\n  scrollToFirstResponseMessage: true,\n  \n  // Customize animation\n  scrollAnimationDuration: Duration(milliseconds: 300),\n  scrollAnimationCurve: Curves.easeOut,\n)\n\n// Or use convenient preset configurations:\nScrollBehaviorConfig.smooth() // Smooth easeInOutCubic curve\nScrollBehaviorConfig.bouncy() // Bouncy elasticOut curve\nScrollBehaviorConfig.fast()   // Quick scrolling with minimal animation\nScrollBehaviorConfig.decelerate() // Starts fast, slows down\nScrollBehaviorConfig.accelerate() // Starts slow, speeds up\n```\n\n#### Use Case: Preventing Long Responses from Auto-Scrolling\n\nWhen an AI returns a long response in multiple parts, scrollToFirstResponseMessage ensures users see the beginning of the response rather than being automatically scrolled to the end. This is crucial for readability, especially with complex information.\n\n**For optimal scroll behavior with long responses:**\n1. Mark the first message in a response with `'isStartOfResponse': true`\n2. Link related messages in a chain using a shared `'responseId'` property\n3. Set `scrollToFirstResponseMessage: true` in your configuration\n\n### Message Bubble Customization\n\n```dart\nMessageOptions(\n  // Basic options\n  showTime: true,\n  showUserName: true,\n  \n  // Styling\n  bubbleStyle: BubbleStyle(\n    userBubbleColor: Colors.blue.withOpacityCompat(0.1),\n    aiBubbleColor: Colors.white,\n    userNameColor: Colors.blue.shade700,\n    aiNameColor: Colors.purple.shade700,\n    bottomLeftRadius: 22,\n    bottomRightRadius: 22,\n    enableShadow: true,\n  ),\n)\n```\n\n### Custom Bubble Builder\n\nCreate completely custom message bubbles with full control over styling and behavior:\n\n```dart\nAiChatWidget(\n  // ... other parameters\n  customBubbleBuilder: (context, message, isCurrentUser, defaultBubble) {\n    // Wrapper approach: enhance default bubble\n    return Container(\n      margin: EdgeInsets.symmetric(horizontal: 16, vertical: 4),\n      decoration: BoxDecoration(\n        borderRadius: BorderRadius.circular(16),\n        boxShadow: [\n          BoxShadow(\n            color: Colors.black.withOpacity(0.1),\n            blurRadius: 4,\n            offset: Offset(0, 2),\n          ),\n        ],\n      ),\n      child: defaultBubble,\n    );\n    \n    // Or create completely custom UI:\n    // return MyCustomBubbleWidget(message: message, isCurrentUser: isCurrentUser);\n  },\n)\n```\n\n## 🚀 AI Actions System\n\n**Transform your chat into a powerful AI agent platform!** The AI Actions System allows your AI to execute real functions, display rich results, and maintain human oversight - taking your chat beyond simple text exchanges.\n\n### ⚡ Quick Start with AI Actions\n\n```dart\nimport 'package:flutter_gen_ai_chat_ui/flutter_gen_ai_chat_ui.dart';\n\nclass MyAiChat extends StatefulWidget {\n  @override\n  _MyAiChatState createState() =\u003e _MyAiChatState();\n}\n\nclass _MyAiChatState extends State\u003cMyAiChat\u003e {\n  late ChatMessagesController _controller;\n  \n  @override\n  Widget build(BuildContext context) {\n    return AiActionProvider(\n      config: AiActionConfig(\n        actions: [\n          // Define what your AI can do\n          AiAction(\n            name: 'calculate',\n            description: 'Perform mathematical calculations',\n            parameters: [\n              ActionParameter.number(name: 'a', description: 'First number', required: true),\n              ActionParameter.number(name: 'b', description: 'Second number', required: true),\n              ActionParameter.string(\n                name: 'operation', \n                description: 'Math operation',\n                required: true,\n                enumValues: ['add', 'subtract', 'multiply', 'divide']\n              ),\n            ],\n            handler: (params) async {\n              final a = params['a'] as num;\n              final b = params['b'] as num;\n              final op = params['operation'] as String;\n              \n              double result;\n              switch (op) {\n                case 'add': result = a + b; break;\n                case 'subtract': result = a - b; break;\n                case 'multiply': result = a * b; break;\n                case 'divide': result = a / b; break;\n                default: throw 'Unknown operation';\n              }\n              \n              return ActionResult.createSuccess({\n                'result': result,\n                'equation': '$a $op $b = $result'\n              });\n            },\n            // Custom UI for results\n            render: (context, status, params, {result, error}) {\n              if (status == ActionStatus.completed \u0026\u0026 result?.data != null) {\n                return Card(\n                  child: Padding(\n                    padding: EdgeInsets.all(16),\n                    child: Text(\n                      result!.data['equation'],\n                      style: TextStyle(fontSize: 18, fontWeight: FontWeight.bold),\n                    ),\n                  ),\n                );\n              }\n              return SizedBox.shrink();\n            },\n          ),\n        ],\n      ),\n      child: AiChatWidget(\n        // Your existing chat configuration\n        currentUser: currentUser,\n        aiUser: aiUser,\n        controller: _controller,\n        onSendMessage: _handleMessage,\n      ),\n    );\n  }\n  \n  void _handleMessage(ChatMessage message) {\n    // Add user message\n    _controller.addMessage(message);\n    \n    // Simulate AI deciding to use an action\n    if (message.text.contains('calculate')) {\n      _executeCalculation(message.text);\n    }\n  }\n  \n  void _executeCalculation(String userMessage) async {\n    final actionHook = AiActionHook.of(context);\n    \n    // AI parses user message and calls action\n    final result = await actionHook.executeAction('calculate', {\n      'a': 15,\n      'b': 3,\n      'operation': 'multiply'\n    });\n    \n    // Add AI response with result\n    _controller.addMessage(ChatMessage(\n      text: result.success ? \n        'I calculated that for you: ${result.data['equation']}' : \n        'Sorry, calculation failed: ${result.error}',\n      user: aiUser,\n    ));\n  }\n}\n```\n\n### 🎨 Action Features\n\n#### **1. Function Calling with Validation**\n```dart\nAiAction(\n  name: 'send_email',\n  description: 'Send an email to a contact',\n  parameters: [\n    ActionParameter.string(\n      name: 'to',\n      description: 'Recipient email address',\n      required: true,\n      validator: (email) =\u003e email.contains('@'),  // Custom validation\n    ),\n    ActionParameter.string(\n      name: 'subject',\n      description: 'Email subject',\n      required: true,\n    ),\n    ActionParameter.string(\n      name: 'priority',\n      description: 'Email priority level',\n      enumValues: ['low', 'normal', 'high'],  // Constrained options\n      defaultValue: 'normal',\n    ),\n  ],\n  handler: (params) async {\n    // Your email sending logic\n    await sendEmailService(params);\n    return ActionResult.createSuccess({'sent': true});\n  },\n)\n```\n\n#### **2. Human-in-the-Loop Confirmations**\n```dart\nAiAction(\n  name: 'delete_file',\n  description: 'Delete a file from storage',\n  parameters: [...],\n  confirmationConfig: ActionConfirmationConfig(\n    title: 'Delete File',\n    message: 'This action cannot be undone. Continue?',\n    required: true,  // Always ask for confirmation\n  ),\n  handler: (params) async {\n    // Only executed after user confirms\n    await deleteFile(params['filename']);\n    return ActionResult.createSuccess();\n  },\n)\n```\n\n#### **3. Real-time Status Updates**\n```dart\nAiAction(\n  name: 'generate_report',\n  description: 'Generate a comprehensive report',\n  render: (context, status, params, {result, error}) {\n    switch (status) {\n      case ActionStatus.executing:\n        return Card(\n          child: Row(children: [\n            CircularProgressIndicator(),\n            Text('Generating report...'),\n          ]),\n        );\n      case ActionStatus.completed:\n        return ReportWidget(data: result!.data);\n      case ActionStatus.failed:\n        return ErrorWidget(error: error!);\n      default:\n        return SizedBox.shrink();\n    }\n  },\n  handler: (params) async {\n    // Long-running operation with progress updates\n    return await generateComplexReport(params);\n  },\n)\n```\n\n#### **4. Event Streaming \u0026 Monitoring**\n```dart\nclass MyAiChat extends StatefulWidget {\n  @override\n  _MyAiChatState createState() =\u003e _MyAiChatState();\n}\n\nclass _MyAiChatState extends State\u003cMyAiChat\u003e {\n  late StreamSubscription\u003cActionEvent\u003e _actionSubscription;\n  \n  @override\n  void initState() {\n    super.initState();\n    \n    // Listen to all action events\n    _actionSubscription = AiActionProvider.of(context).events.listen((event) {\n      switch (event.type) {\n        case ActionEventType.started:\n          print('Action ${event.actionName} started');\n          break;\n        case ActionEventType.completed:\n          print('Action ${event.actionName} completed: ${event.result?.data}');\n          break;\n        case ActionEventType.failed:\n          print('Action ${event.actionName} failed: ${event.error}');\n          break;\n      }\n    });\n  }\n  \n  @override\n  void dispose() {\n    _actionSubscription.cancel();\n    super.dispose();\n  }\n}\n```\n\n### 💡 Integration with AI Providers\n\n#### **OpenAI Function Calling**\n```dart\n// Convert actions to OpenAI function format\nfinal actionHook = AiActionHook.of(context);\nfinal functions = actionHook.getActionsForFunctionCalling();\n\n// Send to OpenAI with functions\nfinal response = await openAI.createChatCompletion(\n  messages: messages,\n  functions: functions,\n  functionCall: 'auto',\n);\n\n// Execute function if AI wants to call one\nif (response.functionCall != null) {\n  final result = await actionHook.handleFunctionCall(\n    response.functionCall.name,\n    json.decode(response.functionCall.arguments),\n  );\n}\n```\n\n#### **Custom AI Integration**\n```dart\nvoid _processAIMessage(String userMessage) async {\n  // Your AI logic decides which action to call\n  if (_shouldCalculate(userMessage)) {\n    final actionHook = AiActionHook.of(context);\n    \n    // Extract parameters from user message\n    final params = _parseCalculationParams(userMessage);\n    \n    // Execute action\n    final result = await actionHook.executeAction('calculate', params);\n    \n    // Show result in chat\n    _controller.addMessage(ChatMessage(\n      text: 'Result: ${result.data}',\n      user: aiUser,\n    ));\n  }\n}\n```\n\n### 🛡️ Security \u0026 Best Practices\n\n- **Parameter Validation**: All inputs are validated before execution\n- **User Confirmation**: Sensitive actions require explicit user approval  \n- **Error Isolation**: Failed actions don't crash your app\n- **Timeout Protection**: Long-running actions can be cancelled\n- **Type Safety**: Full Dart type checking for all parameters\n- **Event Auditing**: Complete log of all action executions\n\n### 📚 Examples Included\n\nThe package includes complete working examples:\n- **Weather Actions** - API calls with rich UI display\n- **Calculator Actions** - Mathematical operations with validation\n- **Unit Converter** - Type conversions with error handling\n- **AI Integration** - Pattern matching and function calling\n\nRun the example app to see AI Actions in action:\n```bash\ncd example/\nflutter run\n```\n\n---\n\n## 🎯 Showcase\n\n### Featured Apps Using This Package\n- **AI Customer Support Bot** - SaaS company with 10K+ daily conversations\n- **Educational Tutor App** - Language learning with interactive chat\n- **Healthcare Assistant** - HIPAA-compliant patient communication\n- **E-commerce Support** - Real-time shopping assistance\n- **Gaming Guild Chat** - Team communication with file sharing\n\n*Want your app featured? [Submit a showcase request](https://github.com/hooshyar/flutter_gen_ai_chat_ui/issues/new?template=showcase.md)*\n\n### Community \u0026 Support\n\n- **🐛 [Issue Tracker](https://github.com/hooshyar/flutter_gen_ai_chat_ui/issues)** - Report bugs and request features\n- **⭐ [Star on GitHub](https://github.com/hooshyar/flutter_gen_ai_chat_ui)** - Show your support!\n\n## Recent Updates (v2.4.2+)\n\n### 🔧 Bug Fixes \u0026 Improvements\n\n- **Fixed Streaming Animation Disable**: The `enableAnimation: false`, `enableMarkdownStreaming: false`, and `streamingWordByWord: false` parameters now work correctly. Previously, markdown messages would always stream regardless of these settings.\n\n- **Added Focus Control**: New `autofocus` and `focusNode` support in `InputOptions` for better input field control.\n  ```dart\n  InputOptions(\n    autofocus: true,          // Auto-focus input on widget load\n    focusNode: myFocusNode,   // External focus control\n  )\n  ```\n\n- **Enhanced Factory Constructors**: `InputOptions.minimal()` and `InputOptions.glassmorphic()` now support the new focus parameters.\n\n### What Developers Say\n\n\u003e *\"The streaming text animation is incredibly smooth and the file attachment system saved us weeks of development.\"* - **Sarah Chen, Senior Flutter Developer**\n\n\u003e *\"Best chat UI package I've used. The performance with large message lists is outstanding.\"* - **Ahmed Hassan, Mobile Team Lead**\n\n\u003e *\"Finally, a chat package that actually works well for AI applications. The streaming feature is exactly what we needed.\"* - **Maria Rodriguez, Product Manager**\n\n---\n\n**Made with ❤️ by the Flutter community** | **Star ⭐ this repo if it helped you!**","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhooshyar%2Fflutter_gen_ai_chat_ui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhooshyar%2Fflutter_gen_ai_chat_ui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhooshyar%2Fflutter_gen_ai_chat_ui/lists"}