Apps often require users to enter information into a text field. Forexample, we might be working on an app that requires our users to log in with anemail address and password combination.

In order to make our apps secure and easy to use, we can check whether theinformation the user has provided is valid. If the user has correctly filledout the form, we can process the information. If the user submits incorrectinformation, we can display a friendly error message letting them know what wentwrong.

In this example, we’ll see how to add validation to a form with a singletext field.

Directions

• Create a Form with a GlobalKey
• Add a TextFormField with validation logic
• Create a button to validate and submit the form

1. Create a Form with a GlobalKey

First, we’ll need a Formto work with. The Form Widget acts as a container to group and validatemultiple form fields.

When we create the form, we’ll also need to provide aGlobalKey.This will uniquely identify the Form that we’re working with, and will allowus to validate the form in a later step.

// Define a Custom Form Widget
class MyCustomForm extends StatefulWidget {
  @override
  MyCustomFormState createState() {
    return MyCustomFormState();
  }
}
// Define a corresponding State class. This class will hold the data related to
// the form.
class MyCustomFormState extends State<MyCustomForm> {
  // Create a global key that will uniquely identify the Form widget and allow
  // us to validate the form
  //
  // Note: This is a `GlobalKey<FormState>`, not a GlobalKey<MyCustomFormState>!
  final _formKey = GlobalKey<FormState>();
  @override
  Widget build(BuildContext context) {
    // Build a Form widget using the _formKey we created above
    return Form(
      key: _formKey,
      child: // We'll build this out in the next steps!
    );
  }
}

Tip:Using a GlobalKey is the recommended way to access a form. However, if youhave a more complex widget tree, you can use theForm.of method toaccess the form within nested widgets.

2. Add a TextFormField with validation logic

We have our Form in place, but we haven’t provided a way for our users toenter text! This is the job of aTextFormField.The TextFormField Widget renders a material design text input and knows how todisplay validation errors when they occur.

How can we validate the input? By providing a validator function to theTextFormField. If there is an error with the information the user hasprovided, the validator function must return a String containingan error message. If there are no errors, the function should not returnanything.

In this example, we will create a validator that ensures the TextFormFieldisn’t empty. If it is empty, we will return a friendly error message!

TextFormField(
  // The validator receives the text the user has typed in
  validator: (value) {
    if (value.isEmpty) {
      return 'Please enter some text';
    }
    return null;
  },
);

3. Create a button to validate and submit the form

Now that we have a form with a text field, we’ll need to provide a button theuser can tap to submit the information.

When the user attempts to submit the form, we’ll need to check if the form isvalid. If it is, we will show a success message. If the text field has nocontent, we’ll want to display the error message.

RaisedButton(
  onPressed: () {
    // Validate will return true if the form is valid, or false if
    // the form is invalid.
    if (_formKey.currentState.validate()) {
      // If the form is valid, display a snackbar. In the real world, you'd
      // often want to call a server or save the information in a database
      Scaffold
          .of(context)
          .showSnackBar(SnackBar(content: Text('Processing Data')));
    }
  },
  child: Text('Submit'),
);

How does this work?

In order to validate the form, we’ll need to use the _formKey created instep 1. We can use the _formKey.currentState method to access theFormState,which is automatically created by Flutter when we build a Form.

The FormState class contains the validate method. When the validate methodis called, it will run the validator function for each text field in the form.If everything looks good, the method returns true. If any text field containserrors, it will display the error message for each invalid text field and returnfalse.

Complete example

import 'package:flutter/material.dart';
void main() => runApp(MyApp());
class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final appTitle = 'Form Validation Demo';
    return MaterialApp(
      title: appTitle,
      home: Scaffold(
        appBar: AppBar(
          title: Text(appTitle),
        ),
        body: MyCustomForm(),
      ),
    );
  }
}
// Create a Form Widget
class MyCustomForm extends StatefulWidget {
  @override
  MyCustomFormState createState() {
    return MyCustomFormState();
  }
}
// Create a corresponding State class. This class will hold the data related to
// the form.
class MyCustomFormState extends State<MyCustomForm> {
  // Create a global key that will uniquely identify the Form widget and allow
  // us to validate the form
  //
  // Note: This is a GlobalKey<FormState>, not a GlobalKey<MyCustomFormState>!
  final _formKey = GlobalKey<FormState>();
  @override
  Widget build(BuildContext context) {
    // Build a Form widget using the _formKey we created above
    return Form(
      key: _formKey,
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.start,
        children: <Widget>[
          TextFormField(
            validator: (value) {
              if (value.isEmpty) {
                return 'Please enter some text';
              }
              return null;
            },
          ),
          Padding(
            padding: const EdgeInsets.symmetric(vertical: 16.0),
            child: RaisedButton(
              onPressed: () {
                // Validate will return true if the form is valid, or false if
                // the form is invalid.
                if (_formKey.currentState.validate()) {
                  // If the form is valid, we want to show a Snackbar
                  Scaffold.of(context)
                      .showSnackBar(SnackBar(content: Text('Processing Data')));
                }
              },
              child: Text('Submit'),
            ),
          ),
        ],
      ),
    );
  }
}