Fifty Forms #

Full validation pipeline for Flutter forms -- you provide the layout, we handle the state.

25 built-in validators, async debounce validation, multi-step wizards with custom navigation, draft persistence that survives app kills, and optional builder callbacks that let you replace the navigation buttons, progress indicator, error summary, and submit button individually. Part of Fifty Flutter Kit.

Home	Login Form	Registration	Multi-Step

Why fifty_forms #

• Full validation pipeline, you build the UI -- FiftyFormController handles field registration, 25 built-in validators, async debounce validation, and draft persistence; you provide the layout.
• Wizard forms with custom everything -- FiftyMultiStepForm comes with step validation, progress tracking, and navigation; replace the navigation buttons, progress display, error summary, and submit button individually via optional builders.
• Async validators with debounce -- AsyncCustom<String> debounces server-side checks (username availability, email exists) so API calls fire only when the user pauses typing.
• Draft persistence that survives app kills -- DraftManager auto-saves form state to GetStorage with configurable debounce; restore drafts on next open with a single hasDraft() check.

Installation #

dependencies:
  fifty_forms: ^0.2.1

For Contributors #

dependencies:
  fifty_forms:
    path: ../fifty_forms

Dependencies: fifty_tokens, fifty_theme, fifty_ui, fifty_storage, get_storage

Quick Start #

final controller = FiftyFormController(
  initialValues: {'email': '', 'password': ''},
  validators: {
    'email': [Required(), Email()],
    'password': [Required(), MinLength(8)],
  },
);

Column(
  children: [
    FiftyTextFormField(
      name: 'email',
      controller: controller,
      label: 'Email',
      keyboardType: TextInputType.emailAddress,
    ),
    FiftyTextFormField(
      name: 'password',
      controller: controller,
      label: 'Password',
      obscureText: true,
    ),
    FiftySubmitButton(
      controller: controller,
      label: 'LOGIN',
      onPressed: () => controller.submit((values) async {
        await api.login(values['email'], values['password']);
      }),
    ),
  ],
)

Architecture #

fifty_forms
+-- core/
|   +-- FiftyFormController   # Central state manager
|   +-- FieldState            # Immutable per-field state
+-- validators/
|   +-- Validator             # Sync validator base
|   +-- AsyncValidator        # Async validator with debounce
|   +-- Built-ins             # Required, Email, MinLength, etc.
+-- fields/
|   +-- FiftyTextFormField    # fifty_ui field wrappers
|   +-- FiftyDropdownFormField
|   +-- FiftyCheckboxFormField (+ others)
+-- widgets/
|   +-- FiftyForm             # Form container
|   +-- FiftySubmitButton     # Submit with loading state
|   +-- FiftyMultiStepForm    # Wizard container
|   +-- FiftyFormArray        # Dynamic repeating fields
|   +-- FiftyValidationSummary
+-- models/
|   +-- FormStep              # Step definition for wizards
|   +-- FormStatus            # Form lifecycle enum
+-- persistence/
    +-- DraftManager          # Auto-save via GetStorage

Core Components #

Customization #

Every form UI widget accepts an optional builder callback. When provided, the builder replaces the default FDL rendering while the widget retains ownership of controller listening, state computation, and animations.

Custom Navigation Buttons #

Replace the default back/next/complete buttons on FiftyMultiStepForm:

FiftyMultiStepForm(
  controller: controller,
  steps: mySteps,
  stepBuilder: (context, index, step) => buildStepContent(index),
  onComplete: (values) => api.createUser(values),
  navigationBuilder: (isFirstStep, isLastStep, isSubmitting, onNext, onPrevious) {
    return Row(
      children: [
        if (!isFirstStep)
          TextButton(onPressed: onPrevious, child: const Text('Back')),
        const Spacer(),
        ElevatedButton(
          onPressed: isSubmitting ? null : onNext,
          child: Text(isLastStep ? 'Submit' : 'Continue'),
        ),
      ],
    );
  },
)

Custom Submit Button #

Replace the default FiftyButton on FiftySubmitButton:

FiftySubmitButton(
  controller: controller,
  label: 'SAVE',
  onPressed: () => controller.submit(save),
  buttonBuilder: (isLoading, isDisabled, onPressed, label) {
    return AnimatedContainer(
      duration: const Duration(milliseconds: 200),
      child: ElevatedButton(
        onPressed: onPressed,
        child: isLoading
            ? const SizedBox(width: 16, height: 16, child: CircularProgressIndicator(strokeWidth: 2))
            : Text(label),
      ),
    );
  },
)

Custom Validation Summary #

Replace the default error card on FiftyValidationSummary:

FiftyValidationSummary(
  controller: controller,
  contentBuilder: (errors, onFieldTap) {
    return Column(
      crossAxisAlignment: CrossAxisAlignment.start,
      children: errors.entries.map((e) {
        return GestureDetector(
          onTap: onFieldTap != null ? () => onFieldTap(e.key) : null,
          child: Text('${e.key}: ${e.value}', style: const TextStyle(color: Colors.red)),
        );
      }).toList(),
    );
  },
)

Custom Progress Indicator #

Replace the default step circles on FiftyFormProgress:

FiftyFormProgress(
  currentStep: 2,
  totalSteps: 4,
  stepLabels: ['Account', 'Profile', 'Preferences', 'Review'],
  contentBuilder: (currentStep, totalSteps, stepLabels) {
    return LinearProgressIndicator(value: currentStep / totalSteps);
  },
)

Builder Signatures #

All builders are optional. Omit them to use the default FDL UI.

API Reference #

FiftyFormController #

The central state manager for forms. Handles field registration, value tracking, validation (sync and async), and form submission.

final controller = FiftyFormController(
  initialValues: {'name': '', 'age': 0},
  validators: {
    'name': [Required(), MinLength(2)],
    'age': [Required(), Min(18)],
  },
  onValidationChanged: (isValid) => print('Valid: $isValid'),
);

// Get/set values
controller.setValue('name', 'John');
final name = controller.getValue<String>('name');

// Check state
controller.isValid;      // All fields valid?
controller.isDirty;      // Any field changed?
controller.isValidating; // Async validation running?

// Field operations
controller.registerField('newField', initialValue: '');
controller.unregisterField('fieldToRemove');
controller.markTouched('name');
controller.markAllTouched();

// Actions
await controller.validate();          // Validate all fields
await controller.validateField('email'); // Validate single field
controller.clearErrors();             // Clear all validation errors
controller.reset();                   // Reset to initial values
controller.clear();                   // Clear all values

// Submit
await controller.submit((values) async {
  await api.save(values);
});

// Cleanup
controller.dispose();

Key Properties:

FieldState #

Immutable state container for a form field. Tracks the current value, validation error, and interaction state.

class FieldState<T> {
  final T? value;           // Current value
  final String? error;      // Validation error
  final bool isTouched;     // Field has been focused
  final bool isDirty;       // Value differs from initial
  final bool isValidating;  // Async validation running

  bool get isValid => error == null && !isValidating;
  bool get hasError => error != null;
}

// Usage
final state = controller.getFieldState('email');
if (state.isTouched && state.hasError) {
  print(state.error);
}

FormStatus #

Enum representing the form lifecycle status:

Validators #

String Validators:

Number Validators:

Date Validators:

Password Validators:

Comparison Validators:

Form Fields #

Wrapper components for fifty_ui widgets that integrate with FiftyFormController:

UI Widgets #

Configuration #

FiftyFormController #

FiftyMultiStepForm #

FormStep #

DraftManager #

FiftyFormArray #

Usage Patterns #

Strong Password Validation #

validators: {
  'password': [
    Required(message: 'Password is required'),
    MinLength(8, message: 'At least 8 characters'),
    HasUppercase(message: 'Must contain uppercase letter'),
    HasLowercase(message: 'Must contain lowercase letter'),
    HasNumber(message: 'Must contain a number'),
    HasSpecialChar(message: 'Must contain special character'),
  ],
}

Password Confirmation #

validators: {
  'password': [Required(), MinLength(8)],
  'confirmPassword': [Required(), Equals('password', message: 'Passwords must match')],
}

Custom Validators #

// Synchronous
Custom<String>((value) {
  if (value?.contains('banned') == true) {
    return 'Contains banned word';
  }
  return null;
})

// Asynchronous with debounce
AsyncCustom<String>(
  (value) async {
    final exists = await api.checkUsername(value);
    return exists ? 'Username taken' : null;
  },
  debounce: Duration(milliseconds: 500),
)

Composite Validators #

// And -- all must pass
And([Required(), MinLength(8), HasUppercase()])

// Or -- at least one must pass
Or([Email(), Pattern(phoneRegex)])

Multi-Step Form #

FiftyMultiStepForm(
  controller: controller,
  steps: [
    FormStep(
      title: 'Account',
      description: 'Create your credentials',
      fields: ['email', 'password'],
    ),
    FormStep(
      title: 'Profile',
      fields: ['name', 'bio'],
      isOptional: true,
    ),
    FormStep(
      title: 'Review',
      fields: [],
      validator: (values) {
        if (values['bio']?.isEmpty == true) {
          return 'Consider adding a bio';
        }
        return null;
      },
    ),
  ],
  stepBuilder: (context, index, step) => _buildStep(index),
  onComplete: (values) => api.createUser(values),
  onStepChanged: (step) => print('Now on step $step'),
  showProgress: true,
  validateOnNext: true,
  nextLabel: 'NEXT',
  previousLabel: 'BACK',
  completeLabel: 'COMPLETE',
)

Dynamic Form Arrays #

FiftyFormArray(
  controller: controller,
  name: 'addresses',
  minItems: 1,
  maxItems: 5,
  itemBuilder: (context, index, remove) => Column(
    children: [
      FiftyTextFormField(
        name: 'addresses[$index].street',
        controller: controller,
        label: 'Street',
      ),
      FiftyTextFormField(
        name: 'addresses[$index].city',
        controller: controller,
        label: 'City',
      ),
      IconButton(
        icon: Icon(Icons.delete),
        onPressed: remove,
      ),
    ],
  ),
  addButtonBuilder: (add) => FiftyButton(
    label: 'Add Address',
    onPressed: add,
    variant: FiftyButtonVariant.ghost,
    icon: Icons.add,
  ),
)

Accessing Array Values:

// Get single field
final street = controller.getArrayValue<String>('addresses', 0, 'street');

// Set single field
controller.setArrayValue('addresses', 0, 'city', 'New York');

// Get all items as list of maps
final addresses = controller.getArrayValues('addresses');
// Returns: [{'street': '123 Main', 'city': 'NYC'}, ...]

// Get array length
final count = controller.getArrayLength('addresses');

// Remove item (shifts subsequent indices)
controller.removeArrayItem('addresses', 1);

Draft Persistence #

// Initialize storage once at app start
await DraftManager.initStorage();

// Create draft manager
final draftManager = DraftManager(
  controller: controller,
  key: 'registration_form',
  debounce: Duration(seconds: 2),
);

// Start auto-save
draftManager.start();

// Check for existing draft
if (await draftManager.hasDraft()) {
  final restored = await draftManager.restoreDraft();
  if (restored != null) {
    showSnackBar('Draft restored');
  }
}

// Manual save
await draftManager.saveDraft();

// Clear after successful submission
await controller.submit((values) async {
  await api.save(values);
  await draftManager.clearDraft();
});

// Stop auto-save (keeps draft)
draftManager.stop();

// Cleanup
draftManager.dispose();

FiftySubmitButton #

FiftySubmitButton(
  controller: controller,
  label: 'SUBMIT',
  icon: Icons.send,
  loadingText: 'SAVING...',
  onPressed: () => controller.submit((values) async {
    await api.save(values);
  }),
  disableWhenInvalid: true,
  expanded: true,
  variant: FiftyButtonVariant.primary,
)

Platform Support #

Fifty Design Language Integration #

This package is part of Fifty Flutter Kit:

• fifty_tokens - All spacing, radius, and typography values sourced from design tokens
• fifty_ui - Form field widgets wrap FDL components (FiftyTextField, FiftyDropdown, FiftyCheckbox, etc.)
• fifty_theme - Consumes theming from the FDL theme system; no custom theme classes defined
• fifty_storage - Draft persistence layer integrates with the FDL storage abstraction

Version #

Current: 0.2.1

License #

MIT License - see LICENSE for details.

Part of Fifty Flutter Kit.