TextFormField class

A FormField that contains a TextField.

This is a convenience widget that wraps a TextField widget in a FormField.

A Form ancestor is not required. The Form allows one to save, reset, or validate multiple fields at once. To use without a Form, pass a GlobalKey<FormFieldState> (see GlobalKey) to the constructor and use GlobalKey.currentState to save or reset the form field.

When a controller is specified, its TextEditingController.text defines the initialValue. If this FormField is part of a scrolling container that lazily constructs its children, like a ListView or a CustomScrollView, then a controller should be specified. The controller's lifetime should be managed by a stateful widget ancestor of the scrolling container.

If a controller is not specified, initialValue can be used to give the automatically generated controller an initial value.

When the widget has focus, it will prevent itself from disposing via its underlying EditableText's AutomaticKeepAliveClientMixin.wantKeepAlive in order to avoid losing the selection. Removing the focus will allow it to be disposed.

Remember to call TextEditingController.dispose of the TextEditingController when it is no longer needed. This will ensure any resources used by the object are discarded.

By default, decoration will apply the ThemeData.inputDecorationTheme for the current context to the InputDecoration, see InputDecoration.applyDefaults.

For a documentation about the various parameters, see TextField.

TextFormField(
  decoration: const InputDecoration(
    icon: Icon(Icons.person),
    hintText: 'What do people call you?',
    labelText: 'Name *',
  ),
  onSaved: (String? value) {
    // This optional block of code can be used to run
    // code when the user saves the form.
  },
  validator: (String? value) {
    return (value != null && value.contains('@')) ? 'Do not use the @ char.' : null;
  },
)

See also:

• material.io/design/components/text-fields.html
• TextField, which is the underlying text field without the Form integration.
• InputDecorator, which shows the labels and other visual elements that surround the actual text editing widget.
• Learn how to use a TextEditingController in one of our cookbook recipes.