Orientação gerada a partir de informações públicas. Apenas para referência.
Reactive_forms é um pacote Flutter que implementa uma abordagem orientada a modelos para manipulação e validação de formulários, inspirado nos Formulários Reativos do Angular. Permite aos desenvolvedores criar formulários dinâmicos e reativos com modelos estruturados, validação em tempo real e gerenciamento fácil de estado. O pacote suporta estruturas complexas de formulários, formulários aninhados e validadores personalizados, promovendo código limpo e sustentável. Integra-se perfeitamente à árvore de widgets do Flutter e fornece estados observáveis dos formulários para atualizações eficientes da interface.
Casos de uso
Construindo formulários dinâmicos e complexos
Implementando validação em tempo real do formulário
Gerenciando entradas de formulário aninhadas ou agrupadas
Criando componentes de formulário reutilizáveis
Gerenciando validação assíncrona de formulários
Principais recursos
Arquitetura de formulário orientada por modelo
Validação em tempo real com validadores personalizados
Suporte para formulários aninhados e agrupados
Mudanças observáveis no estado do formulário
Integração com o ecossistema reativo do Flutter
Indicado para
Desenvolvedores familiarizados com formulários reativos do Angular
Projetos que exigem lógica de formulário complexa
Aplicativos que precisam de validação de formulário robusta
Equipes que priorizam código de formulário sustentável
Considerações
Requer conhecimento dos conceitos de programação reativa
Pode ter uma curva de aprendizado mais acentuada para iniciantes
Documentação limitada em comparação com pacotes principais
README original
Snapshot do README original do repositório-fonte vinculado. Consulte o repositório para o conteúdo mais recente.
Reactive Forms
This is a model-driven approach to handling form inputs and validations, heavily inspired by Angular's Reactive Forms.
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:
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:
Stringget 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 controlthis.form.control('name').value = 'John';
// Set values to controls by setting the value to the formthis.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:
Extend the Validator class and override the validate method.
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`.classRequiredTrueValidatorextendsValidator<dynamic> {
constRequiredTrueValidator() : super();
@overrideMap<String, dynamic>? validate(AbstractControl<dynamic> control) {
return control.isNotNull &&
control.value isbool &&
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 isbool &&
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 numberexpect(cardNumber.valid, false);
expect(cardNumber.hasError('pattern'), true);
The above code is a Unit Test extracted from Reactive Forms tests.
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 example:
In the previous code, we added two more fields to the form: password and passwordConfirmation. Both fields are required, and the password must be at least 8 characters long.
However, the most important thing here is that we have attached a validator to the FormGroup. This validator is a custom validator, and the implementation is as follows:
classMustMatchValidatorextendsValidator<dynamic> {
finalString controlName;
finalString matchingControlName;
MustMatchValidator({
requiredthis.controlName,
requiredthis.matchingControlName,
}) : super();
@overrideMap<String, dynamic>? validate(AbstractControl<dynamic> control) {
final form = control asFormGroup;
final formControl = form.control(controlName);
final matchingFormControl = form.control(matchingControlName);
if (formControl.value != matchingFormControl.value) {
matchingFormControl.setErrors({'mustMatch': true});
// Force messages to show up as soon as possible
matchingFormControl.markAsTouched();
} else {
matchingFormControl.removeError('mustMatch');
}
returnnull;
}
}
Fortunately, you don't have to implement a custom must match validator because we have already included it in the reactive_forms package, so you should reuse it. The previous form definition becomes:
Sometimes, you want to perform a validation against a remote server. These operations are more time-consuming and need to be done asynchronously.
For example, you want to validate that the email the user is currently typing in a registration form is unique and not already used in your application. Asynchronous Validators are just another tool, so use them wisely.
Asynchronous Validators are very similar to their synchronous counterparts, with the following difference:
Asynchronous validation executes after synchronous validation and is performed only if the synchronous validation is successful. This check allows forms to avoid potentially expensive async validation processes (such as an HTTP request) if the more basic validation methods have already found invalid input.
After asynchronous validation begins, the form control enters a pending state. You can inspect the control's pending property and use it to give visual feedback about the ongoing validation operation.
Code speaks louder than words, so let's see an example.
Let's implement the previously mentioned example: the user is typing an email in a registration form, and you want to validate that the email is unique in your system. We will implement a custom async validator for that purpose.
final form = FormGroup({
'email': FormControl<String>(
validators: [
Validators.required, // Traditional required and email validatorsValidators.email,
],
asyncValidators: [
UniqueEmailAsyncValidator(), // Custom asynchronous validator :)
],
),
});
We have declared a simple Form with an email field that is required and must have a valid email value. We have also included a custom async validator that will validate if the email is unique. Let's see the implementation of our new async validator:
/// Validator that validates the user's email is unique by sending a request to/// the server.classUniqueEmailAsyncValidatorextendsAsyncValidator<dynamic> {
@overrideFuture<Map<String, dynamic>?> validate(AbstractControl<dynamic> control) async {
final error = {'unique': false};
final isUniqueEmail = await_getIsUniqueEmail(control.value.toString());
if (!isUniqueEmail) {
control.markAsTouched();
return error;
}
returnnull;
}
/// Simulates a time-consuming operation (e.g., a server request).Future<bool> _getIsUniqueEmail(String email) {
// Simple array that simulates emails stored in the server DB.final storedEmails = ['johndoe@email.com', 'john@email.com'];
returnFuture.delayed(
constDuration(seconds: 5),
() => !storedEmails.contains(email),
);
}
}
Note the use of control.markAsTouched() to force the validation message to show up as soon as possible.
The previous implementation was a simple validator that receives the AbstractControl and returns a Future that completes 5 seconds after its call and performs a simple check: if the value of the control is contained in the server array of emails.
If you want to see Async Validators in action with a full example using widgets and animations to provide feedback to the user, we strongly advise you to visit our Wiki. We have not included the full example in this README.md file to simplify things here and not to anticipate things that we will see later in this doc.
The validator Validators.delegateAsync() is another way to implement a custom validator. For more reference,
check the Custom Validators section.
Debounce Time in Async Validators
Asynchronous validators have a debounce time that is useful if you want to minimize requests to a remote API. The debounce time is set in milliseconds, and the default value is 250 milliseconds.
You can set a different debounce time as an optional argument in the FormControl constructor.
final control = FormControl<String>(
asyncValidators: [UniqueEmailAsyncValidator()],
asyncValidatorsDebounceTime: 1000, // Sets a 1-second debounce time.
);
Custom Debounce Time in Async Validators
You can also specify a custom debounce time for a single async validator. This is useful when you have multiple async validators with different debounce time requirements.
final control = FormControl<String>(
asyncValidators: [
Validators.debounced(
Validators.delegateAsync((control) async {
// Your validation logic herereturnnull;
}),
500, // Debounce time in milliseconds
),
],
);
Custom Debounce Time in delegateAsync Validator
The Validators.delegateAsync() function now accepts an optional debounceTime parameter, defaulting to 0. This allows for immediate execution or custom debouncing for asynchronous validation.
final form = fb.group({
'userName': FormControl<String>(
asyncValidators: [
Validators.delegateAsync((control) async {
// Simulate a call to a backend serviceawaitFuture<void>.delayed(Duration(seconds: 1));
if (control.value == 'existingUser') {
return {'unique': true};
}
returnnull;
}, debounceTime: 300),
],
),
});
You can also use it without a debounce time:
final form = fb.group({
'userName': FormControl<String>(
asyncValidators: [
Validators.delegateAsync((control) async {
// Simulate a call to a backend serviceawaitFuture<void>.delayed(Duration(seconds: 1));
if (control.value == 'existingUser') {
return {'unique': true};
}
returnnull;
}), // No debounce time
],
),
});
Composing Validators
To explain what Composing Validators is, let's see an example:
We want to validate a text field of an authentication form.
In this text field, the user can write an email or a phone number, and we want to make sure that the information is correctly formatted. We must validate that the input is a valid email or a valid phone number.
final phonePattern = '<some phone regex pattern>';
final form = FormGroup({
'user': FormControl<String>(
validators: [
Validators.composeOR([
Validators.email,
Validators.pattern(phonePattern),
])
],
),
});
Note that Validators.composeOR receives a collection of validators as an argument and returns a validator.
With Validators.composeOR, we are telling the FormControl that if at least one validator evaluates as VALID, then the control is VALID. It's not necessary for both validators to evaluate to valid.
Another example could be to validate multiple Credit Card numbers. In that case, you have several regular expression patterns for each type of credit card. So, the user can introduce a card number, and if the information matches at least one pattern, then the information is considered valid.
final form = FormGroup({
'cardNumber': FormControl<String>(
validators: [
Validators.composeOR([
Validators.pattern(americanExpressCardPattern),
Validators.pattern(masterCardPattern),
Validators.pattern(visaCardPattern),
])
],
),
});
One Of Validator
The oneOf validator is used to validate that the control's value is one of the values in the provided collection. For String values, the comparison can be made case-sensitive or insensitive.
final form = FormGroup({
'fruit': FormControl<String>(
validators: [
Validators.oneOf(['apple', 'banana', 'orange']),
],
),
});
Groups of Groups :grin:
FormGroup is not restricted to containing only FormControl; it can nest other FormGroups, so you can create more complex Forms.
Suppose you have a Registration Wizard with several screens. Each screen collects specific information, and at the end, you want to collect all that information as one piece of data:
Note how we have set the data type to a FormControl. Although this is not mandatory when
declaring a Form, we highly recommend this syntax as a good practice or to use the FormBuilder
syntax.
Using FormBuilder(read the FormBuilder section below):
A simple way to create a wizard is, for example, to wrap a PageView within a ReactiveForm, and each Page inside the PageView can contain a ReactiveForm to collect specific data.
Dynamic Forms with FormArray
FormArray is an alternative to FormGroup for managing any number of unnamed controls. As with FormGroup instances, you can dynamically insert and remove controls from FormArray instances, and the form array instance value and validation status are calculated from its child controls.
You don't need to define a key for each control by name, so this is a great option if you don't know the number of child values in advance.
Let's see a simple example:
final form = FormGroup({
'emails': FormArray<String>([]), // An empty array of emails
});
We have defined just an empty array. Let's define another array with two controls:
final form = FormGroup({
'emails': FormArray<String>([
FormControl<String>(value: 'john@email.com'),
FormControl<String>(value: 'susan@email.com'),
]),
});
Note that you don't have to specify the name of the controls inside the array.
If we output the value of the previous form group, we will get something like this:
print(form.value);
{"emails":["john@email.com","susan@email.com"]}
Let's dynamically add another control:
final array = form.control('emails') asFormArray<String>;
// Adding another email
array.add(
FormControl<String>(value: 'caroline@email.com'),
);
print(form.value);
Another way to add controls is to assign values directly to the array:
// Given: an empty array of stringsfinal array = FormArray<String>([]);
// When: set value to the array
array.value = ["john@email.com", "susan@email.com", "caroline@email.com"];
// Then: the array is no longer emptyexpect(array.controls.length, 3);
// And: the array has a control for each inserted valueexpect(array.controls('0').value, "john@email.com");
expect(array.controls('1').value, "susan@email.com");
expect(array.controls('2').value, "caroline@email.com");
To get a control from the array, you must pass the index position as a String. This is because FormGroup and FormArray inherit from the same parent class, and FormControl gets the controls by name (String).
A more advanced example:
// An array of contactsfinal contacts = ['john@email.com', 'susan@email.com', 'caroline@email.com'];
// A form with a list of selected emailsfinal form = FormGroup({
'selectedEmails': FormArray<bool>([], // An empty array of controls
validators: [emptyAddressee], // Validates that at least one email is selected
),
});
// Get the array of controlsfinal formArray = form.control('selectedEmails') asFormArray<bool>;
// Populates the array of controls.// For each contact, add a boolean form control to the array.
formArray.addAll(
contacts.map((email) => FormControl<bool>(value: true)).toList(),
);
// Validates that at least one email is selectedMap<String, dynamic> emptyAddressee(AbstractControl control) {
final emails = (control asFormArray<bool>).value;
return emails.any((isSelected) => isSelected)
? null
: {'emptyAddressee': true};
}
// An array of groups using FormBuilderfinal addressArray = fb.array([
fb.group({'city': 'Sofia', 'zipCode': 1000}),
fb.group({'city': 'Havana', 'zipCode': 10400}),
]);
or just:
// An array of groups using a very simple syntaxfinal addressArray = fb.array([
{'city': 'Sofia', 'zipCode': 1000},
{'city': 'Havana', 'zipCode': 10400},
]);
You can iterate over groups as follows:
final cities = addressArray.controls
.map((control) => control asFormGroup)
.map((form) => form.control('city').value)
.toList();
A common mistake is to declare an array of groups as FormArray.
An array of FormGroup must be declared as FormArray() or as FormArray<Map<String, dynamic>>().
FormBuilder
The FormBuilder provides syntactic sugar that shortens the creation of instances of a FormGroup, FormArray, and FormControl. It reduces the amount of boilerplate needed to build complex forms.
Groups
// Creates a groupfinal form = fb.group({
'name': 'John Doe',
'email': ['', Validators.required, Validators.email],
'password': Validators.required,
});
The previous code is equivalent to the following:
final form = FormGroup({
'name': FormControl<String>(value: 'John Doe'),
'email': FormControl<String>(value: '', validators: [Validators.required, Validators.email]),
'password': FormControl<String>(validators: [Validators.required]),
});
Arrays
// Creates an arrayfinal aliases = fb.array(['john', 'little john']);
Control
// Creates a control of type String with a required validatorfinal control = fb.control<String>('', [Validators.required]);
Control State
// Create a groupfinal group = fb.group(
// Creates a control with a default value and disabled state'name': fb.state(value: 'john', disabled: true),
);
Nested Controls
To retrieve nested controls, you can specify the name of the control as a dot-delimited string that defines the path to the control:
final form = FormGroup({
'address': FormGroup({
'city': FormControl<String>(value: 'Sofia'),
'zipCode': FormControl<int>(value: 1000),
}),
});
// Get nested control valuefinal city = form.control('address.city');
print(city.value); // Outputs: Sofia
Reactive Form Widgets
So far, we have only defined our model-driven form, but how do we bind the form definition with our Flutter widgets? Reactive Form Widgets are the answer.
The example above ignores the emailConfirmation and passwordConfirmation fields previously seen for simplicity.
How to Customize Error Messages?
Validation messages can be defined at two different levels:
Reactive Widget level.
Global/Application level.
1. Reactive Widget Level.
Each reactive widget, like ReactiveTextField, ReactiveDropdownField, and all others, has the
validationMessages property as an argument of their constructors. To define custom
validation messages at the widget level, just provide the validationMessages property with the
corresponding text values for each error, as shown below:
@overrideWidgetbuild(BuildContext context) {
returnReactiveForm(
formGroup: this.form,
child: Column(
children: <Widget>[
ReactiveTextField(
formControlName: 'name',
validationMessages: {
'required': (error) => 'The name must not be empty'
},
),
ReactiveTextField(
formControlName: 'email',
validationMessages: {
'required': (error) => 'The email must not be empty',
'email': (error) => 'The email value must be a valid email'
},
),
ReactiveTextField(
formControlName: 'password',
obscureText: true,
validationMessages: {
'required': (error) => 'The password must not be empty',
'minLength': (error) => 'The password must have at least 8 characters'
},
),
],
),
);
}
Reactive Forms has a utility class called ValidationMessage that provides access to
common validation messages: required, email, pattern, and so on. So instead of writing 'required', you
could use ValidationMessage.required as the key of validation messages:
returnReactiveTextField(
formControlName: 'email',
validationMessages: {
ValidationMessage.required: (error) => 'The email must not be empty',
ValidationMessage.email: (error) => 'The email value must be a valid email',
},
);
Nice, isn't it? ;)
2. Global/Application Level.
You can also define custom validation messages at a higher level, for example, at the application
level. When a reactive widget looks for an error message text, it first looks at the widget-level
definition. If it doesn't find any config at the widget level, then it looks at the global config
definition.
The global definition of validation messages allows you to define error messages in a centralized
way and relieves you from defining validation messages on each reactive widget of your application.
To define these configs at a higher level, use the widget ReactiveFormConfig and
define the validationMessages.
Here is an example of the global definition for custom validation messages:
Validation Messages with Error Arguments:
classMyAppextendsStatelessWidget{
constMyApp({super.key});
@overrideWidgetbuild(BuildContext context) {
returnReactiveFormConfig(
validationMessages: {
ValidationMessage.required: (error) => 'Field must not be empty',
ValidationMessage.email: (error) => 'Must enter a valid email',
},
child: MaterialApp(
home: Scaffold(
body: constCenter(
child: Text('Hello Flutter Reactive Forms!'),
),
),
),
);
}
}
Parameterized Validation Messages
You can enrich the validation messages using parameters of the error instance. In the next example,
we are giving a more complete validation error to the user:
final form = FormGroup({
'password': FormControl<String>(
validators: [Validators.minLength(8)],
),
});
ReactiveTextField(
formControlName: 'password',
validationMessage: {
ValidationMessages.minLength: (error) =>
'The password must be at least ${(error as Map)['requiredLength']} characters long'
},
)
This will show the message: The password must be at least 8 characters long
When do Validation Messages Appear?
Touching a Control
Even when the FormControl is invalid, validation messages will begin to show up when the FormControl is touched. That means when the user taps on the ReactiveTextField widget and then removes focus or completes the text editing.
You can initialize a FormControl as touched to force the validation messages to show up the very first time the widget builds.
final form = FormGroup({
'name': FormControl<String>(
value: 'John Doe',
validators: [Validators.required],
touched: true,
),
});
When you set a value to a FormControl from code and want to show validation messages,
you must call the FormControl.markAsTouched() method:
setname(String newName) {
final formControl = this.form.control('name');
formControl.value = newName;
formControl.markAsTouched(); // If newName is invalid, then validation messages will show up in the UI
}
To mark all children controls of a FormGroup and FormArray as touched, you must call markAllAsTouched().
final form = FormGroup({
'name': FormControl<String>(
value: 'John Doe',
validators: [Validators.required],
touched: true,
),
});
// Marks all children as touched
form.markAllAsTouched();
Overriding Reactive Widgets Show Errors Behavior
The second way to customize when to show error messages is to override the showErrors method in reactive widgets.
Let's suppose you want to show validation messages not only when it is invalid and touched (default behavior), but also when it's dirty:
ReactiveTextField(
formControlName: 'email',
// Override default behavior and show errors when: INVALID, TOUCHED, and DIRTY
showErrors: (control) => control.invalid && control.touched && control.dirty,
),
A control becomes dirty when its value changes through the UI.
The setErrors method of the controls can optionally mark it as dirty too.
Enable/Disable Submit Button
For a better User Experience, sometimes we want to enable/disable the Submit button based on the validity of the Form. Achieving this behavior, even in a great framework like Flutter, can sometimes be hard and can lead to individual implementations for each Form of the same application, plus boilerplate code.
We will show you two different approaches to accomplish this very easily:
Separating the Submit Button into a different Widget.
Notice the use of ReactiveForm.of(context) to get access to the nearest FormGroup up the widget's tree.
In the previous example, we separated the implementation of the submit button into a different widget. The reason behind this is that we want to rebuild the submit button each time the validity of the FormGroup changes. We don't want to rebuild the entire Form, just the button.
How is that possible? Well, the answer is in the expression:
final form = ReactiveForm.of(context);
The expression above has two important responsibilities:
Obtains the nearest FormGroup up the widget's tree.
Registers the current context with the changes in the FormGroup so that if the validity of the FormGroup changes, the current context is rebuilt.
Using the ReactiveFormConsumer widget:
The ReactiveFormConsumer widget is a wrapper around the ReactiveForm.of(context) expression so that we can reimplement the previous example as follows:
It is entirely up to you to decide which of the above two approaches to use, but note that to access the FormGroup via ReactiveForm.of(context), the consumer widget must always be down in the tree of the ReactiveForm widget.
Focus/Unfocus a FormControl
There are some cases where we want to add or remove focus on a UI TextField without the user's interaction. For those particular cases, you can use the FormControl.focus() or FormControl.unfocus() methods.
final form = fb.group({'name': 'John Doe'});
FormControl control = form.control('name');
control.focus(); // UI text field gets focus, and the device keyboard pops up
control.unfocus(); // UI text field loses focus
You can also set focus directly from the Form like this:
final form = fb.group({'name': ''});
form.focus('name'); // UI text field gets focus, and the device keyboard pops up
final form = fb.group({
'person': fb.group({
'name': '',
}),
});
// Set focus to a nested control
form.focus('person.name');
Focus Flow Between Text Fields
Another example is when you have a form with several text fields, and each time the user completes editing in one field, you want to request the next focus field using keyboard actions:
final form = fb.group({
'name': ['', Validators.required],
'email': ['', Validators.required, Validators.email],
'password': ['', Validators.required],
});
When you remove focus from a control, the control is marked as touched. This means that the validation error messages will show up in the UI. To prevent validation messages from showing up, you can optionally set the touched argument to false.
// Remove the focus from the control and mark it as untouched.this.form.unfocus(touched: false);
How to Enable/Disable a Widget
To disable a widget like ReactiveTextField, all you need to do is mark the control as disabled:
final form = FormGroup({
'name': FormControl<String>(),
});
FormControl control = form.control('name');
// The control is disabled, and the widget in the UI is also disabled.
control.markAsDisabled();
When a control is disabled, it is exempt from validation checks and excluded from the aggregate
value of any parent. Its status is DISABLED.
To retrieve all values of a FormGroup or FormArray regardless of the disabled status of children, use
FormControl.rawValue or FormArray.rawValue, respectively.
ReactiveTextField has more in common with TextFormField than with TextField. As we all know, TextFormField is a wrapper around the TextField widget that brings some extra capabilities, such as Form validations with properties like autovalidate and validator. In the same way, ReactiveTextField is a wrapper around TextField that handles the features of validations in its own different way.
ReactiveTextField has all the properties that you can find in a common TextField. It can be customized as much as you want, just like a simple TextField or a TextFormField. In fact, most of the code was taken from the original TextFormField and ported to have a reactive behavior that binds itself to a FormControl in a two-way binding.
Below is an example of how to create some ReactiveTextField with some common properties:
Because of the two-way binding capability of the ReactiveTextField with a FormControl,
the widget does not include properties like controller, validator, autovalidate, or onSaved.
The FormControl is responsible for handling validation as well as change
notifications.
It does include some events like onChanged, onTap, onEditingComplete,
and onSubmitted.
Supported Reactive Form Field Widgets
ReactiveTextField
ReactiveDropdownField
ReactiveSwitch
ReactiveCheckbox
ReactiveRadio
ReactiveSlider
ReactiveCheckboxListTile
ReactiveSwitchListTile
ReactiveRadioListTile
Bonus Field Widgets
ReactiveDatePicker
ReactiveTimePicker
Other Reactive Forms Widgets
ReactiveForm
ReactiveFormConsumer
ReactiveFormBuilder
ReactiveFormArray
ReactiveValueListenableBuilder
ReactiveStatusListenableBuilder
Advanced Reactive Field Widgets
We are trying to keep reactive_forms from bloating with third-party dependencies. This is why there is
a separate library, reactive_forms_widgets, which is still under construction, that provides
a variety of more advanced field widgets. To know more about how to install it, please visit the library repo and read the documentation about the widgets it contains.
We have explained the common usage of a ReactiveTextField throughout this documentation.
ReactiveDropdownField
ReactiveDropdownField, like all the other reactive field widgets, is almost the same as its native version, DropdownButtonFormField, but adds two-way binding capabilities. The code is ported from the original native implementation. It has all the capability of styles and themes of the native version.
As you can see from the above example, the usage of ReactiveDropdownField is almost the same as the usage of a common DropdownButtonFormField, except for the additional formControlName and validationMessages properties.
ReactiveValueListenableBuilder to Listen for Value Changes in a FormControl
If you want to rebuild a widget each time a FormControl value changes, you can use the ReactiveValueListenableBuilder widget.
In the following example, we are listening for changes in lightIntensity. We change that value with a ReactiveSlider and show the value in a Text widget all the time:
The main differences are that ReactiveForm is a StatelessWidget, so it doesn't save the instance of the FormGroup. You must declare the instance of the FormGroup in a StatefulWidget or resolve it from some Provider (state management library).
// Using ReactiveForm in a StatelessWidget and resolving the FormGroup from a providerclassSignInFormextendsStatelessWidget{
@overrideWidgetbuild(BuildContext context) {
final viewModel = Provider.of<SignInViewModel>(context, listen: false);
returnReactiveForm(
formGroup: viewModel.form,
child: ReactiveTextField(
formControlName: 'email',
),
);
}
}
// Using ReactiveForm in a StatefulWidget and declaring the FormGroup in the state.classSignInFormextendsStatefulWidget{
@override_SignInFormStatecreateState() => _SignInFormState();
}
class_SignInFormStateextendsState<SignInForm> {
final form = fb.group({
'email': Validators.email,
});
@overrideWidgetbuild(BuildContext context) {
returnReactiveForm(
formGroup: this.form,
child: ReactiveTextField(
formControlName: 'email',
),
);
}
}
If you declare a FormGroup in a StatelessWidget, the group will be destroyed and recreated each time the instance of the StatelessWidget is destroyed and created. Therefore, you must preserve the FormGroup in a state or in a Bloc/Provider/etc.
On the other hand, ReactiveFormBuilder is implemented as a StatefulWidget, so it holds the created FormGroup in its state. That way, it's safe to declare the FormGroup in a StatelessWidget or get it from a Bloc/Provider/etc.
Although Reactive Forms can be used with any state management library or even without one at all, Reactive Forms reaches its maximum potential when used in combination with a state management library like the Provider plugin.
This way, you can separate UI logic from business logic, and you can define the FormGroup inside a business logic class and then expose that class to widgets with a mechanism like the one the Provider plugin provides.
ReactiveFormsGenerator is the code generator for reactive_forms that will save you tons of time and make your forms type-safe.
There is no reason to write code manually! Let the code generation work for you.
How to Create a Custom Reactive Widget?
Reactive Forms is not limited to just common widgets in Forms like text, dropdowns, sliders, switch fields, etc. You can easily create custom widgets that two-way bind to FormControls and create your own set of Reactive Widgets.
In our Wiki, you can find a tutorial on how to create your custom Reactive Widget.
Reactive Forms is not a fancy widgets package. It is not a library that brings new Widgets with new shapes, colors, or animations. It lets you decide the shapes, colors, and animations you want for your widgets but frees you from the responsibility of gathering and validating the data. It also keeps the data in sync between your model and your widgets.
Reactive Forms does not pretend to replace the native widgets that you commonly use in your Flutter projects, like TextFormField, DropdownButtonFormField, or CheckboxListTile. Instead, it brings new two-way binding capabilities and many more features to those same widgets.
What Reactive Forms Is
Reactive Forms provides a model-driven approach to handling form inputs whose values change over time. It's heavily inspired by Angular Reactive Forms.
It lets you focus on business logic and saves you time from collecting, validating, and maintaining synchronization between your models and widgets.
It removes boilerplate code and gives you the possibility to write clean code by defining a separation between model and UI with minimal effort.
It integrates perfectly well with common state management libraries like Provider, Bloc, and many other good libraries the community has created.
Migration Versions
Visit the Migration Guide to see
more details about different version breaking changes.