Reactive Forms

This is a model-driven approach to handling form inputs and validations, heavily inspired by Angular's Reactive Forms.

Table of Contents

• Getting Started
  • Minimum Requirements
  • Installation and Usage
• Creating a Form
• Getting/Setting Form Data
• Validators
  • Predefined Validators
  • Custom Validators
  • Pattern Validator
  • FormGroup Validators
  • Password and Password Confirmation
  • Asynchronous Validators
  • Debounce Time in Async Validators
  • Composing Validators
• Groups of Groups
• Dynamic Forms with FormArray
• Arrays of Groups
• FormBuilder
  • Groups
  • Arrays
  • Control
  • Control State
• Reactive Form Widgets
• How to Customize Error Messages
  • Reactive Widget Level

Getting Started

For help getting started with Flutter, view the online documentation, which offers tutorials, samples, guidance on mobile development, and a full API reference.

Minimum Requirements

• Dart SDK: ^3.7.0
• Flutter: ">=3.29.0"

For using Reactive Forms in projects below Flutter 2.8.0, please use version <= 10.7.0 of Reactive Forms.

For using Reactive Forms in projects below Flutter 2.2.0, please use version <= 10.2.0 of Reactive Forms.

For using Reactive Forms in projects with Flutter 1.17.0, please use version 7.6.3 of Reactive Forms.

Reactive Forms v8.x includes the intl package. If a version conflict is present, you should use dependency_overrides to temporarily override all references to intl and set the one that better fits your needs.

Installation and Usage

Once you're familiar with Flutter, you can install this package by adding reactive_forms to the dependencies list of your pubspec.yaml file as follows:

dependencies:
  flutter:
    sdk: flutter

  reactive_forms: ^18.2.2

Then, run the command flutter packages get in the console.

Creating a Form

A form is composed of multiple fields or controls.

To declare a form with the fields name and email, it's as simple as:

final form = FormGroup({
  'name': FormControl<String>(value: 'John Doe'),
  'email': FormControl<String>(),
});

Default Values

Notice in the example above that for the name field, we have set a default value. For the email field, the default value is null.

How to Get/Set Form Data

Given the FormGroup:

final form = FormGroup({
  'name': FormControl<String>(value: 'John Doe'),
  'email': FormControl<String>(value: 'johndoe@email.com'),
});

You can get the value of a single FormControl as simply as:

String get name => this.form.control('name').value;

You can also get the complete Form data as follows:

print(form.value);

The previous code prints the following output:

{
  "name": "John Doe",
  "email": "johndoe@email.com"
}

FormGroup.value returns an instance of Map<String, dynamic> with each field and its value.

To set values to controls, you can use two approaches:

// Set the value directly to the control
this.form.control('name').value = 'John';

// Set values to controls by setting the value to the form
this.form.value = {
  'name': 'John',
  'email': 'john@email.com',
};

What about Validators?

You can add validators to a FormControl as follows:

final form = FormGroup({
  'name': FormControl<String>(validators: [Validators.required]),
  'email': FormControl<String>(validators: [
    Validators.required,
    Validators.email,
  ]),
});

If at least one FormControl is invalid, then the FormGroup is invalid.

There are common predefined validators, but you can also implement custom validators.

Predefined Validators

FormControl

• Validators.required
• Validators.requiredTrue
• Validators.email
• Validators.number
• Validators.min
• Validators.max
• Validators.minLength
• Validators.maxLength
• Validators.pattern
• Validators.creditCard
• Validators.equals
• Validators.compose
• Validators.composeOR
• Validators.any
• Validators.contains
• Validators.oneOf

FormGroup

• Validators.mustMatch
• Validators.compare

FormArray

• Validators.minLength
• Validators.maxLength
• Validators.any
• Validators.contains

Custom Validators

All validators are instances of classes that inherit from the Validator abstract class. To implement a custom validator, you can follow two different approaches:

1. Extend the Validator class and override the validate method.
2. Implement a custom validator function/method and use it with the Validators.delegate(...) validator.

Let's implement a custom validator that validates that a control's value must be true:

Inheriting from the Validator class:

Let's create a class that extends Validator and overrides the validate method:

/// Validator that validates the control's value must be `true`.
class RequiredTrueValidator extends Validator<dynamic> {
  const RequiredTrueValidator() : super();

  @override
  Map<String, dynamic>? validate(AbstractControl<dynamic> control) {
    return control.isNotNull &&
           control.value is bool &&
           control.value == true
    ? null
    : {'requiredTrue': true};
  }
}

The validate method is a function that receives the control to validate and returns a Map. If the value of the control is valid, the function returns null; otherwise, it returns a Map with the error key and custom information. In the previous example, we defined requiredTrue as the error key and true as the custom information.

To use the new validator class, we provide an instance of it in the FormControl definition.

final form = FormGroup({
  'acceptLicense': FormControl<bool>(
    value: false,
    validators: [
      RequiredTrueValidator(), // Providing the new custom validator
    ],
  ),
});

Using the Validators.delegate() validator:

Sometimes, it's more convenient to implement a custom validator in a separate method/function than in a new class. In that case, it's necessary to use the Validators.delegate() validator. It creates a validator that delegates the validation to the external function/method.

final form = FormGroup({
  'acceptLicense': FormControl<bool>(
    value: false,
    validators: [
      Validators.delegate(_requiredTrue) // Delegates validation to a custom function
    ],
  ),
});

/// Custom function that validates that the control's value must be `true`.
Map<String, dynamic>? _requiredTrue(AbstractControl<dynamic> control) {
  return control.isNotNull &&
         control.value is bool &&
         control.value == true
  ? null
  : {'requiredTrue': true};
}

Check the Migration Guide to learn more about custom validators after version 15.0.0 of the package.

Pattern Validator

Validator.pattern is a validator that comes with Reactive Forms. Validation using regular expressions has always been a very useful tool to solve validation requirements. Let's see how we can validate American Express card numbers:

American Express card numbers start with 34 or 37 and have 15 digits.

const americanExpressCardPattern = r'^3[47][0-9]{13}$';

final cardNumber = FormControl<String>(
  validators: [Validators.pattern(americanExpressCardPattern)],
);

cardNumber.value = '395465465421'; // Not a valid number

expect(cardNumber.valid, false);
expect(cardNumber.hasError('pattern'), true);

The above code is a Unit Test extracted from Reactive Forms tests.

If we print the value of FormControl.errors:

print(cardNumber.errors);

We will get a Map like this:

{
  "pattern": {
    "requiredPattern": "^3[47][0-9]{13}$",
    "actualValue": 395465465421
  }
}

FormGroup Validators

There are special validators that can be attached to a FormGroup. In the next section, we will see an example of that.

What about Password and Password Confirmation?

There are some cases where we want to implement a Form where the validation of one field depends on the value of another. For example, a sign-up form with email and emailConfirmation or password and passwordConfirmation.

For those cases, we can implement a custom validator as a class and attach it to the FormGroup. Let's see an e