Skip to content
Blog

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

  • onSaved fires only when FormState.save() runs. Keep it dumb: copy the raw string into a model field. No side effects, no network calls.
  • onChanged fires 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.