QuicUI - Server-Driven UI Framework for Flutter

QuicUI is a powerful Server-Driven UI (SDUI) framework for Flutter that enables you to build, update, and deliver dynamic user interfaces without redeploying your app. Define your UI as JSON and render it natively at runtime. Backend is fully optional - works standalone with local data, or integrates with any cloud backend via plugins.

🚀 Features

• Instant Updates: Ship UI changes without App Store/Play Store approval
• JSON-Driven: Define widgets in JSON, render natively in Flutter
• Standalone Usage: Works with local JSON data - no backend required
• Backend Optional: Integrate with Supabase, Firebase, REST API, or custom backends
• Real-Time Sync: Live UI updates with minimal latency (when backend is available)
• Dynamic Navigation: Control routes from the backend or locally
• Form Management: Server-side or local forms with built-in validation
• Dynamic Theming: Update branding and styles in real-time
• Offline-First: Lightning-fast local database (ObjectBox) for offline apps
• Extensible: Custom widgets, actions, and native integrations
• Cross-Platform: iOS, Android, Web, Windows, macOS, Linux

📦 What's New

v1.0.5+ (October 31, 2025) - Comprehensive Error Handling System ✨ NEW

• ✅ Multi-Layer Error Handling: Runtime recovery with graceful fallbacks
• ✅ Build-Time Validation: JSON schema checking before deployment
• ✅ CLI Validation Tool: Project-wide validation with watch mode
• ✅ Dependency Analysis: Detect missing assets and broken references
• ✅ Performance Analysis: Identify deep nesting and excessive children
• ✅ Accessibility Checking: Ensure compliance with accessibility standards
• ✅ Security Scanning: Detect potential security vulnerabilities
• ✅ Comprehensive Logging: Detailed error context for debugging
• ✅ Zero Production Impact: Error handling compiled out in release builds
• ✅ IDE Ready: Real-time validation support for future IDE integrations

v1.0.5 (October 31, 2025) - Enhanced Padding/Margin & Task Manager ✨

• ✅ Enhanced Padding/Margin Support: {"all": 16}, {"horizontal": 20, "vertical": 10} syntax
• ✅ Improved Container Rendering: Better support for complex decoration patterns
• ✅ Task Manager Example: Complete production-ready task management app
• ✅ Layout Overflow Fixes: Proper Expanded widget usage for responsive layouts
• ✅ Icon Spacing Improvements: Better touch targets and visual spacing
• ✅ Deprecated API Fixes: Updated to latest Flutter APIs (Color, Radio widgets)
• ✅ JSON Structure Enhancements: Support for nested container hierarchies
• ✅ Mobile-Optimized UI: Perfect spacing and alignment for mobile devices

v1.0.4 (October 30, 2025) - Callback Action System ✨

• ✅ Generic callback action system (navigate, setState, apiCall, custom)
• ✅ JSON-driven interactive flows without Dart code
• ✅ Action chaining with success/error handling
• ✅ Variable binding with ${variable_name} syntax
• ✅ 29 comprehensive unit tests (100% passing)
• ✅ 4,500+ lines of complete documentation
• ✅ 15 working JSON examples (login, registration, CRUD)
• ✅ Custom handler registry for app-specific logic
• ✅ Built-in state management for interactive UIs

v1.0.1 (October 30, 2025) - Production Release ✨

• ✅ Backend-agnostic plugin architecture
• ✅ 70+ pre-built widgets fully functional
• ✅ BLoC state management complete
• ✅ Offline-first architecture with sync
• ✅ Real-time UI sync support
• ✅ ObjectBox local persistence
• ✅ Comprehensive backend integration guides
• ✅ 5 complete example applications
• ✅ 11,000+ lines of documentation
• ✅ 267/267 tests passing (100%)
• ✅ Published to pub.dev

🎯 Quick Start

Installation

flutter pub add quicui

Minimal Setup (No Backend)

import 'package:quicui/quicui.dart';

void main() {
  runApp(QuicUIApp(home: MyApp()));
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    // Render local JSON without any backend
    final jsonData = {
      'type': 'column',
      'properties': {'mainAxisAlignment': 'center'},
      'children': [
        {
          'type': 'text',
          'properties': {'text': 'Hello from Local JSON!', 'fontSize': 24}
        }
      ]
    };
    
    final screen = Screen.fromJson(jsonData);
    return UIRenderer.render(screen);
  }
}

📚 Documentation

Getting Started

• Quick Start Guide - 5-minute setup guide with plugin examples
• Plugin Architecture - Understanding the plugin system

Backend Integration

• Backend Integration Guide - How to build custom DataSource implementations
• API Reference - Complete DataSource interface documentation
• Supabase Backend Package - Supabase integration with examples
• Firebase Integration - Firebase backend setup
• Custom Backend - Build your own DataSource

Examples & Patterns

• Example Applications - REST API and custom backend examples
• Scaffold Counter App - Complete counter app with Scaffold widget
• Supabase Examples - See the Supabase package for Supabase-specific examples
• Testing Guide - Mock backends and unit testing
• Performance Guide - Caching, optimization, and best practices

Technical Documentation

• Architecture Guide - System design and component structure
• Database Strategy - ObjectBox integration and local storage
• Development Roadmap - Phase-by-phase breakdown with milestones

Example Applications

See /example folder for:

• Task Manager Runner ✨ NEW - Production-ready task management app with advanced UI patterns
• Counter App - Simple state management
• Form App - Input handling and validation
• Todo App - CRUD operations
• Offline Sync App - Offline-first synchronization
• Dashboard App - Complex layouts and theming

Task Manager Example Features ✨ NEW

• Advanced Layout Patterns: Nested containers with proper spacing
• Mobile-Optimized Design: Perfect touch targets and visual hierarchy
• Complex JSON Structure: Real-world example of sophisticated UI composition
• Responsive Layout: Proper Expanded widget usage to prevent overflow
• Enhanced Styling: Modern Material Design with shadows, borders, and gradients

🔌 Official Plugins

QuicUI supports backend integration through official plugins. Mix and match plugins based on your needs:

QuicUI Supabase

Complete Supabase backend integration with real-time synchronization and offline-first architecture.

Features:

• Real-time UI updates via WebSocket
• Offline-first with automatic sync
• Screen management and search
• Conflict resolution
• PostgreSQL database integration

Installation:

dependencies:
  quicui: ^1.0.2
  quicui_supabase: ^2.0.1

Usage:

import 'package:quicui_supabase/quicui_supabase.dart';

final dataSource = SupabaseDataSource(
  'https://your-project.supabase.co',
  'your-anon-key',
);
await QuicUIService().initializeWithDataSource(dataSource);

📖 View Supabase Plugin Documentation

---

🏗️ Architecture Overview

Layered Architecture

┌─────────────────────────────┐
│   Presentation Layer (UI)   │
│  Widgets, Factory, Rendering│
└─────────────────────────────┘
              ↓
┌─────────────────────────────┐
│ Business Logic Layer        │
│ State, Forms, Actions       │
└─────────────────────────────┘
              ↓
┌─────────────────────────────┐
│   Data Layer                │
│ API, Database, Cache        │
└─────────────────────────────┘

Core Components

Component	Purpose
Widget Factory	Convert JSON to Flutter widgets
JSON Parser	Parse and validate JSON schemas
State Manager	Centralized reactive state
Action Executor	Handle navigation, API, events
Form System	Build & validate forms server-side
Local DB (ObjectBox)	Fast, persistent local storage
Theme Manager	Dynamic runtime theming
Sync Manager	Offline-first sync strategy

🎨 Supported Widgets

Layout Widgets

• Container, Column, Row, Stack, Center
• Scaffold, AppBar, BottomNav, Drawer
• ListView, GridView, SingleChildScrollView

Input Widgets

• TextField, Checkbox, Radio, DropDown
• Switch, DatePicker, FilePicker

Display Widgets

• Text, Image, Icon, Badge, Chip
• Card, Dialog, SnackBar

Advanced Widgets

• Conditional (if/else)
• Loop (dynamic lists)
• Form (with validation)
• Custom (extensible)

🎯 Interactive Callbacks System

Build dynamic, responsive UIs without writing Dart code! Define interactive workflows as JSON - the callback system handles everything from button taps to API calls to state management.

The 4 Generic Actions

Transform any static UI into an interactive app with these 4 reusable actions:

Action	Purpose	Example
navigate	Move between screens	Navigate to login, home, profile
setState	Update UI state dynamically	Toggle loading, show/hide elements
apiCall	Make HTTP requests	Fetch data, submit forms, authenticate
custom	Execute app-specific logic	Email validation, calculations, business logic

Quick Example: Login Screen

{
  "id": "button_login",
  "type": "ElevatedButton",
  "properties": {"label": "Login"},
  "actions": [
    {
      "action": "setState",
      "updates": {"isLoading": true}
    },
    {
      "action": "apiCall",
      "method": "POST",
      "endpoint": "/api/auth/login",
      "body": {
        "email": "${email_input}",
        "password": "${password_input}"
      },
      "onSuccess": {
        "action": "navigate",
        "screen": "home",
        "replace": true
      },
      "onError": {
        "action": "setState",
        "updates": {"error": "Login failed"}
      }
    },
    {
      "action": "setState",
      "updates": {"isLoading": false}
    }
  ]
}

Key Features

✅ Action Chaining - Execute actions sequentially with success/error handling ✅ Variable Binding - Reference form inputs with ${variable_name} ✅ Event Triggers - onPressed, onTap, onLongTap, onChanged, onSubmitted ✅ State Management - Update UI state on-the-fly ✅ Custom Handlers - Register custom validation and business logic functions ✅ Error Handling - Built-in error callbacks with automatic retry ✅ Loading States - Show/hide loading indicators automatically

Complete Examples

• Login Screen - Email/password authentication with loading states
• Registration Form - Multi-field validation and submission
• Data List with CRUD - Create, read, update, delete operations

How to Use

Step 1: Configure Base URL

void main() {
  ApiConfig.baseUrl = 'https://your-api.com';
  runApp(QuicUI());
}

Step 2: Use in JSON

{
  "action": "apiCall",
  "method": "POST",
  "endpoint": "/api/auth/login",
  "body": {"email": "${email}", "password": "${password}"}
}

Step 3: Optional - Add Custom Handlers

CallbackRegistry.register('validateEmail', (context, params) async {
  final email = params['email'] as String;
  if (!email.contains('@')) throw Exception('Invalid email');
  return {'valid': true};
});

Documentation

📖 Complete Callback Guide - 4,500+ lines with:

• All 4 actions with real code examples
• 15 complete JSON examples
• Step-by-step tutorials
• Configuration guide
• Advanced patterns
• Testing examples

�️ Comprehensive Error Handling System ✨ NEW

QuicUI includes a robust error handling and JSON validation system that ensures your apps are resilient and debuggable:

Multi-Layer Error Handling

Runtime Error Recovery

• Graceful error handling with automatic fallback widgets
• Detailed error context and debugging information
• Production-friendly error displays for users
• Debug mode with full error details for developers

Build-Time Validation

• JSON schema validation before deployment
• Dependency checking (missing assets, broken references)
• Performance analysis (deep nesting, excessive children)
• Accessibility compliance checking
• Security vulnerability scanning

CLI Validation Tool

# Validate entire project
dart run quicui:validate

# Validate specific file
dart run quicui:validate --file assets/screens/login.json

# Watch mode for real-time feedback
dart run quicui:validate --watch

# Generate JSON report
dart run quicui:validate --output report.json --strict

Key Features

✅ Automatic Error Handling - No crashes from JSON errors ✅ Detailed Logging - Rich context for debugging issues ✅ Graceful Fallbacks - Users see appropriate error messages ✅ Performance Optimized - Minimal runtime overhead ✅ Comprehensive Validation - Catch errors early in development ✅ IDE Integration - Real-time validation support

Usage Examples

// Error handling is automatic - no try/catch needed
final widget = UIRenderer.render(jsonData);
// Errors are logged, fallback widgets shown, app stays stable

// Validate JSON programmatically
final validator = BuildTimeValidator();
final result = await validator.validateJson(jsonString);

if (!result.isValid) {
  for (final issue in result.issues) {
    print('${issue.severity}: ${issue.message}');
  }
}

Learn More

📖 Complete Error Handling Guide - 1,000+ lines with:

• Runtime error handling patterns
• Build-time validation setup
• CLI tool usage
• Best practices
• Troubleshooting guide
• Performance tips

---

�📝 JSON Schema Example

Enhanced Padding & Margin Support ✨ NEW

QuicUI now supports multiple padding and margin formats for easier styling:

{
  "type": "Container",
  "properties": {
    "padding": {"all": 16},           // Uniform padding
    "margin": {"horizontal": 20, "vertical": 10}, // Symmetric spacing
    "decoration": {
      "color": "#F5F5F5",
      "borderRadius": {"all": 12}
    }
  },
  "children": [...]
}

Supported Formats:

• {"all": 16} - Apply to all sides
• {"horizontal": 20, "vertical": 10} - Symmetric spacing
• {"left": 10, "right": 20, "top": 5, "bottom": 15} - Individual sides
• 16 - Simple number (applies to all sides)

About the ID Field

The id field in widgets is completely optional:

• When to use: When you need to reference the widget from code (testing, state binding, or programmatic updates)
• When to skip: For most widgets - just define type and properties

{
  "type": "text",
  "properties": {"text": "Hello"}
}

This minimal example works perfectly! Add id only if needed:

{
  "id": "greeting_text",
  "type": "text",
  "properties": {"text": "Hello"}
}

Simple Screen

{
  "type": "scaffold",
  "appBar": {
    "type": "appbar",
    "title": "Welcome"
  },
  "body": {
    "type": "column",
    "properties": {"padding": "16"},
    "children": [
      {
        "type": "text",
        "properties": {
          "text": "Hello QuicUI",
          "fontSize": 24,
          "fontWeight": "bold"
        }
      },
      {
        "type": "button",
        "properties": {"label": "Click Me"},
        "events": {
          "onPressed": {
            "action": "navigate",
            "screen": "detail_screen"
          }
        }
      }
    ]
  }
}

Note: All fields except type and properties are optional. The id field is optional and only needed if you want to reference the widget programmatically.

Counter App with Scaffold

{
  "type": "scaffold",
  "appBar": {
    "type": "appBar",
    "title": "Counter App",
    "backgroundColor": "#1976D2"
  },
  "body": {
    "type": "center",
    "child": {
      "type": "column",
      "mainAxisAlignment": "center",
      "crossAxisAlignment": "center",
      "children": [
        {
          "type": "text",
          "properties": {
            "text": "You have pushed the button this many times:",
            "fontSize": 16
          }
        },
        {
          "type": "sizedBox",
          "properties": {"height": 16}
        },
        {
          "type": "container",
          "properties": {
            "padding": "24",
            "decoration": {
              "color": "#E3F2FD",
              "borderRadius": "12"
            }
          },
          "child": {
            "type": "text",
            "properties": {
              "text": "42",
              "fontSize": 72,
              "fontWeight": "bold",
              "color": "#1976D2"
            }
          }
        },
        {
          "type": "sizedBox",
          "properties": {"height": 32}
        },
        {
          "type": "row",
          "mainAxisAlignment": "center",
          "children": [
            {
              "type": "elevatedButton",
              "properties": {
                "label": "−",
                "backgroundColor": "#F44336"
              }
            },
            {
              "type": "sizedBox",
              "properties": {"width": 16}
            },
            {
              "type": "elevatedButton",
              "properties": {
                "label": "+",
                "backgroundColor": "#4CAF50"
              }
            }
          ]
        }
      ]
    }
  },
  "floatingActionButton": {
    "type": "floatingActionButton",
    "icon": "Icons.add",
    "tooltip": "Increment"
  }
}

See Scaffold Counter App Example for complete implementation with state management.

Form with Validation

{
  "type": "form",
  "formId": "contact_form",
  "fields": [
    {
      "type": "textfield",
      "fieldName": "name",
      "label": "Full Name",
      "validators": [
        {"type": "required", "message": "Name is required"},
        {"type": "minLength", "value": 2}
      ]
    },
    {
      "type": "textfield",
      "fieldName": "email",
      "label": "Email",
      "validators": [
        {"type": "required"},
        {"type": "email"}
      ]
    }
  ],
  "submitAction": {
    "type": "api",
    "method": "POST",
    "url": "/api/contact",
    "body": {"name": "${name}", "email": "${email}"}
  }
}

💾 Local Storage (ObjectBox)

QuicUI uses ObjectBox for blazingly fast local storage:

• ⚡ Sub-millisecond queries (0.2ms avg)
• 🔒 ACID transactions for data integrity
• 📦 50x faster than SQLite for typical operations
• 🔄 Built for sync scenarios
• 🔐 Optional encryption support

// Cache UI responses
await QuicUIManager.cache('home', jsonData);

// Retrieve from cache
final cached = await QuicUIManager.getCache('home');

// Offline support with automatic sync
await QuicUIManager.syncOfflineChanges();

🔧 State Management

// Access global state
Consumer<QuicState>(
  builder: (context, state, _) {
    return Text(state.get('userName') ?? 'Guest');
  },
)

// Update state
Provider.of<QuicState>(context, listen: false)
  .set('userName', 'John Doe');

// Listen to events
state.on('userLoggedIn', (data) {
  print('User logged in: $data');
});

🎨 Dynamic Theming

// Define theme as JSON
final theme = {
  "colors": {
    "primary": "#6366F1",
    "secondary": "#EC4899"
  },
  "typography": {
    "heading": {"fontSize": 24, "fontWeight": "bold"}
  }
};

// Apply dynamically at runtime
Provider.of<ThemeManager>(context, listen: false)
  .setTheme(jsonEncode(theme));

🧪 Testing

QuicUI includes comprehensive testing utilities:

// Unit tests for JSON parsing
test('Parse simple widget', () {
  final json = '{"type":"text","properties":{"text":"Hello"}}';
  final widget = QuicWidget.fromJson(jsonDecode(json));
  expect(widget.type, equals('text'));
});

// Widget tests
testWidgets('Render QuicText', (tester) async {
  await tester.pumpWidget(
    MaterialApp(home: Scaffold(body: QuicText(text: 'Hello')))
  );
  expect(find.text('Hello'), findsOneWidget);
});

📊 Performance

Metric	Target	Status
Widget render	< 100ms	✅ Target
DB query	< 10ms	✅ Target (ObjectBox)
Cache hit	< 1ms	✅ Target
Form validation	< 50ms	✅ Target
Network request	< 500ms	✅ Target

🚀 Development Roadmap

Phase 1-2: Foundation & Widgets (Weeks 1-3)

• Core models and JSON parser
• Widget factory and all core widgets
• Basic rendering engine

Phase 3-4: State & Forms (Weeks 3-5)

• State management system
• Action execution engine
• Complete form system

Phase 5-7: Storage, Theming & Polish (Weeks 5-7)

• ObjectBox integration
• Sync mechanism
• Dynamic theming system
• Testing & documentation

Target Release: End of Week 7 (v1.0 production-ready)

See ROADMAP.md for detailed timeline.

🔌 Extensibility

Custom Widgets

class CustomWidgetRegistry {
  static void register(String type, WidgetBuilder builder) {
    // Register custom widget
  }
}

Custom Actions

class CustomActionHandler {
  static void register(String type, ActionHandler handler) {
    // Handle custom actions
  }
}

Custom Validators

class ValidatorRegistry {
  static void register(String type, ValidatorFn validator) {
    // Custom validation logic
  }
}

🔒 Security

• ✅ JSON schema validation prevents injection
• ✅ Encrypted local storage (optional)
• ✅ HTTPS-only API communication
• ✅ Request signing and verification
• ✅ Sandbox for custom code execution

📱 Platform Support

Platform	Status	Min Version
iOS	✅ Full	11.0
Android	✅ Full	5.0 (API 21)
Web	✅ Full	Modern browsers
Windows	✅ Full	10+
macOS	✅ Full	10.13+
Linux	✅ Full	Ubuntu 18.04+

📦 Dependencies

Core Dependencies

• flutter_bloc: ^9.0.0 - State management (BLoC pattern)
• equatable: ^2.0.5 - Value equality
• dio: ^5.7.0 - HTTP client
• objectbox: ^4.1.1 - Local database
• json_annotation: ^4.8.1 - JSON serialization

See pubspec.yaml for complete list.

📖 Examples

Complete example applications are available in the /example folder:

• Basic text and button rendering
• Form with validation
• API integration
• List rendering
• Theme switching
• Offline support
• A/B testing

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

How to Contribute

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Submit a pull request

🐛 Issue Reporting

Found a bug? Please report it on GitHub with:

• Minimal reproducible example
• Flutter/Dart version
• Platform details
• Relevant logs

📞 Support

• 📚 Full Documentation - Complete guides and examples
• 🏗️ Architecture Guide - System design
• 📱 Supabase Integration - Cloud data sync

☕ Love QuicUI?

If you find QuicUI helpful and want to support its development, consider buying me a coffee! Every cup fuels more features, faster updates, and better documentation.

☕ Buy Me a Coffee - Help keep QuicUI growing!

Your support helps us:

• 🚀 Build new features faster
• 📚 Create better documentation
• 🐛 Fix bugs quickly
• 💡 Implement community requests
• 🎯 Maintain long-term support

Every contribution is deeply appreciated! ❤️

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Inspired by:

• Stac - Server-Driven UI inspiration
• Flutter community and best practices
• Open-source SDUI pioneers

🚀 What's Next?

1. Review the Implementation Plan
2. Read the Architecture Guide
3. Follow the Quick Start
4. Check the Development Roadmap

---

Made with ❤️ by the QuicUI team

⭐ If you find QuicUI useful, please give it a star on GitHub!