TextFormField Patterns in Flutter: Controllers, Validators, and Focus
Practical TextFormField patterns: onSaved vs onChanged, initialValue traps, validator contracts, autovalidateMode, and wiring fields into a Form with GlobalKey.
Published on • November 4, 2026
AI Assistant

TextField gives you a box and a controller; TextFormField gives you a slot inside Flutter’s Form system — validation, save, and grouped error display in one widget (docs.flutter.dev).
The Form Skeleton
A Form coordinates its fields through a GlobalKey<FormState>:
final _formKey = GlobalKey<FormState>();
Form(
key: _formKey,
child: Column(
children: [
TextFormField(
decoration: const InputDecoration(labelText: 'Email'),
validator: (v) =>
v == null || !v.contains('@') ? 'Enter a valid email' : null,
onSaved: (v) => _email = v!.trim(),
),
FilledButton(
onPressed: () {
if (_formKey.currentState!.validate()) {
_formKey.currentState!.save();
_submit();
}
},
child: const Text('Submit'),
),
],
),
)
validate() walks every descendant FormField and returns false if any validator returned a message; save() triggers every onSaved. That two-step contract — validate, then save — is the core pattern.
onSaved vs. onChanged
onSavedfires only whenFormState.save()runs. Keep it dumb: copy the raw string into a model field. No side effects, no network calls.onChangedfires on every keystroke. Use it for live formatting (phone masks), enabling a submit button, or cross-field checks — never for your only copy of the value.
If you need the value continuously, own a TextEditingController instead and read controller.text; onChanged is for reactions, controllers are for state.
The initialValue Trap
TextFormField(initialValue:) seeds the field only on first build. If your widget rebuilds because parent state changed, the value doesn’t reset — and conversely, if the Form subtree is recreated with a new key, user input is wiped. For edit screens that load data async, prefer a controller you populate once:
TextFormField(
controller: _nameController, // set text when data arrives
validator: (v) => (v == null || v.isEmpty) ? 'Required' : null,
)
Autovalidation: Validate as You Type
autovalidateMode controls when errors appear:
TextFormField(
autovalidateMode: AutovalidateMode.onUserInteraction, // after first edit
validator: _validatePassword,
)
disabled— only on demand (default).always— immediately, even for untouched fields (usually hostile UX).onUserInteraction— once the user has edited that field: the sweet spot for long forms.
Styling That Stays Accessible
InputDecoration carries both looks and semantics — labelText floats into the hint slot, errorText reserves space so the layout doesn’t jump when validation fails, and helperText/prefixIcon give context without clutter. Always provide labelText rather than relying on hintText alone: hints disappear on focus and vanish for screen readers at the wrong moment.
Own your values with controllers, validate on demand with onUserInteraction, and let Form coordinate — and TextFormField patterns stay predictable no matter how long the form gets.