smart_form_guard 2.0.2

A smart Flutter form wrapper that validates fields, auto-focuses & scrolls to the first invalid field, and provides pleasant visual feedback.

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?

❌ Traditional Forms	✅ Smart Form Guard
Shows all errors at once	Progressive validation (one at a time)
User hunts for invalid fields	Auto-focuses & scrolls to errors
Static error messages	Shake animation + glow effects
No positive feedback	✅ Green checkmarks when valid
Manual state management	Zero configuration needed

---

🚀 Features

Feature	Description
🎯 Auto-focus	Instantly focuses the first invalid field
📜 Auto-scroll	Smoothly scrolls to off-screen errors
🌊 Shake Animation	Eye-catching shake on validation failure
✨ Glow Effects	Red glow for errors, green glow for valid
✅ Valid State	Green borders & checkmarks when correct
📳 Haptic Feedback	Subtle vibration on errors
🔄 Real-time Validation	Optional autovalidate mode
🗂️ Rich Field Types	Text, Email, Password, Phone, Dropdown, Checkbox, DatePicker
📦 Zero Config	Works out of the box

---

📦 Installation

dependencies:
  smart_form_guard: ^2.0.0

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

Widget	Description
SmartField.email()	Email with validation
SmartField.password()	Password with toggle & strength rules
SmartField.required()	Required text field
SmartField.phone()	Phone number validation

Additional Smart Widgets

Widget	Description
SmartDropdown<T>()	Dropdown with validation & icons
SmartCheckbox()	Checkbox for terms/agreements
SmartDatePicker()	Date selection with validation
SmartSubmitButton()	Submit with loading state

---

🎨 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),
)

---

⚙️ SmartForm Options

Property	Type	Description
child	Widget	Form content (required)
onValid	VoidCallback?	Called when form passes validation
onInvalid	VoidCallback?	Called when validation fails
controller	SmartFormController?	External controller for advanced use
enableHapticFeedback	bool	Enable/disable haptics (default: true)

---

🔧 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.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.dev