smart_form_guard #

🛡️ Forms that guide users instead of punishing them.

A smart Flutter form wrapper that validates fields, auto-focuses & scrolls to the first invalid field, and provides pleasant visual feedback with shake animations, soft glow effects, and real-time validation states.

🎬 Demo #

✨ Why smart_form_guard? #

🚀 Features #

📦 Installation #

dependencies:
  smart_form_guard: ^2.2.2

flutter pub get

🎯 Quick Start #

import 'package:smart_form_guard/smart_form_guard.dart';

SmartForm(
  onValid: () => print("Form is valid 🎉"),
  child: Column(
    children: [
      SmartField.email(
        controller: emailController,
        label: "Email",
      ),
      SmartField.password(
        controller: passwordController,
        label: "Password",
      ),
      SmartSubmitButton(
        text: "Create Account",
        icon: Icons.arrow_forward,
      ),
    ],
  ),
);

That's it! No boilerplate. No manual focus management. No manual scroll logic.

📖 Available Widgets #

SmartField Constructors #

Additional Smart Widgets #

🎨 Customization Examples #

Custom Validators #

SmartField(
  controller: usernameController,
  label: 'Username',
  validator: SmartValidators.compose([
    SmartValidators.required('Username is required'),
    SmartValidators.minLength(3, 'At least 3 characters'),
    SmartValidators.pattern(
      RegExp(r'^[a-zA-Z0-9_]+$'),
      'Only letters, numbers, and underscores',
    ),
  ]),
  prefixIcon: Icons.person_outline,
)

Password with Custom Rules #

SmartField.password(
  controller: passwordController,
  label: 'Password',
  minLength: 10,
  requireUppercase: true,
  requireLowercase: true,
  requireDigit: true,
  requireSpecialChar: true,
  autovalidateMode: AutovalidateMode.onUserInteraction,
)

Styled Dropdown #

SmartDropdown<String>(
  label: 'Country',
  hint: 'Select your country',
  prefixIcon: Icons.public,
  value: selectedCountry,
  items: countries.map((c) => DropdownMenuItem(
    value: c.code,
    child: Row(children: [
      Text(c.flag),
      SizedBox(width: 8),
      Text(c.name),
    ]),
  )).toList(),
  validator: (v) => v == null ? 'Required' : null,
  onChanged: (v) => setState(() => selectedCountry = v),
)

Async Validation #

SmartField(
  label: 'Username',
  validator: (v) => v!.isEmpty ? 'Required' : null,
  asyncValidator: (v) async {
    await Future.delayed(Duration(seconds: 1)); // Simulate API
    if (v == 'admin') return 'Username taken';
    return null;
  },
)

Smart Radio Group #

SmartRadioGroup<String>(
  label: 'Role',
  options: [
    SmartRadioOption(value: 'dev', label: 'Developer', icon: Icons.code),
    SmartRadioOption(value: 'des', label: 'Designer', icon: Icons.brush),
  ],
  onChanged: (val) => print(val),
  validator: (v) => v == null ? 'Select a role' : null,
)

⚙️ SmartForm Options #

🔧 SmartValidators #

Pre-built validators with customizable messages:

SmartValidators.required([message])
SmartValidators.email([message])
SmartValidators.phone([message])
SmartValidators.minLength(length, [message])
SmartValidators.maxLength(length, [message])
SmartValidators.pattern(regex, [message])
SmartValidators.password(
  minLength: 8,
  requireUppercase: true,
  requireLowercase: true,
  requireDigit: true,
  requireSpecialChar: false,
)

// Combine multiple:
SmartValidators.compose([...validators])

🧪 Testing #

flutter test

All core functionality is covered with unit tests.

📋 Version 2.2.2 & 2.2.0 Highlights #

• ✅ Static Analysis Fixes: Resolved deprecated API usage for better stability (v2.2.1).
• ✅ Granular Email Validation: Real-time feedback for specific errors (e.g. missing '@', invalid domain).
• ✅ Persistent Valid State: Green glow now appears whenever a field is valid, ensuring clear positive feedback.
• ✅ Real-time Validation: SmartField.email() now defaults to AutovalidateMode.onUserInteraction for immediate feedback.
• ✅ UI Fixes: Enhanced SmartRadioGroup error states with red outlines and labels.

📋 Version 2.1.0 Highlights #

• ✅ Async Validation: Validate fields asynchronously with built-in loading spinners.
• ✅ New Widget: SmartRadioGroup - A premium, animated radio group.
• ✅ New Field: SmartField.confirmPassword() - Built-in password confirmation logic.
• ✅ Enhanced Widgets: Loading indicators added to all fields.

📋 Version 2.0.0 Highlights #

• ✅ New Widgets: SmartDropdown, SmartCheckbox, SmartDatePicker
• ✅ Valid State UI: Green borders, glows, and checkmarks
• ✅ Haptic Feedback: Subtle vibrations on validation errors
• ✅ Autovalidate Mode: Real-time validation support
• ✅ Generic Validators: Type-safe validation for any field type
• ✅ Premium Dropdown: Icons, elevation, and smooth animations

📄 License #

MIT License - see LICENSE for details.

Made with ❤️ for the Flutter community

⭐ Star on GitHub • 🐛 Report Bug • 📦 View on pub.flutter-io.cn