Read page as text

NIB / DOCUMENTATION

Forms and state — NibComponents

Validate text, choose values, and keep input ownership clear.

Open interactive view

Put text fields inside Form

NibInput and NibTextarea extend FormField<String>. A parent Form can validate, save, and reset them. A validator returns null for a valid value or an error message for an invalid one. AutovalidateMode.onUserInteraction is the default.

Use either controller or initialValue; passing both is an assertion error. When controller or focusNode is omitted, the field creates and disposes its own. Dispose the ones your state object creates.

// Fields and method inside your State class.
final formKey = GlobalKey<FormState>();
String savedEmail = '';
String status = '';

Widget buildForm() => Form(
  key: formKey,
  child: Column(mainAxisSize: MainAxisSize.min, children: [
    NibInput(
      label: 'Email',
      keyboardType: TextInputType.emailAddress,
      validator: NibValidators.compose([
        NibValidators.required(),
        NibValidators.email(),
      ]),
      onSaved: (value) => savedEmail = value?.trim() ?? '',
    ),
    NibButton(
      label: 'Check form',
      onPressed: () {
        if (formKey.currentState?.validate() != true) return;
        formKey.currentState!.save();
        setState(() => status = 'Ready for $savedEmail');
      },
    ),
    Text(status),
  ]),
);
APITypeDefaultBehavior
controllerTextEditingController?nullExternal text owner; mutually exclusive with initialValue.
initialValueString?nullSeeds an internally owned controller.
validatorNibValidator?nullReturns an error string or null; Form.validate invokes it.
autovalidateModeAutovalidateModeonUserInteractionControls when the validator runs before explicit Form validation.
errorTextString?nullForced error that takes precedence over validator output and helper text.
minHeightdouble?nullOptional field floor in logical pixels.

Follow a value through validation and saving

A useful form has three separate moments: typing, validation and submission. Typing updates the field’s text controller. validate asks every participating FormField for an error. save runs each onSaved callback, but it does not contact a server. Put the code above inside your screen’s State class and return buildForm from a padded page body. Keep the GlobalKey outside build so the Form remains identifiable across rebuilds.

Press Check form with no email. required returns the first error, so email is not the message you see yet. Enter a malformed address and check again; now required succeeds and email reports the problem. Enter a valid address and the saved value appears below the button. The live form demo uses the same sequence with a required name. Inspect the feedback before and after editing to understand onUserInteraction validation.

If you need to read text while the user is typing, create a TextEditingController in State and pass controller. Dispose it in dispose, and omit initialValue. If you need only the submitted value, onSaved avoids that extra ownership. initialValue is a seed, not a command to overwrite the current draft on every rebuild.

Compose validation rules

NibValidators.compose checks rules in order and returns the first error. Format rules such as email permit an empty value, so add required when a field is mandatory.

NibTextarea adds minLines: 3 by default, optional maxLines, maxLength, and a showCounter switch. A server validation error belongs in errorText; clear or replace it when the server accepts a new value.

APITypeDefaultBehavior
NibValidators.required()NibValidatordefault messageRejects null, empty, and whitespace-only text.
NibValidators.email()NibValidatordefault messageChecks a non-empty email-shaped value.
NibTextarea.minLinesint3Initial minimum visible text lines.
NibTextarea.showCounterboolfalseShows the length counter when enabled.

Keep choices controlled

NibCheckbox.value and NibSwitch.value are controlled: read the current boolean from State and assign the callback’s proposed value inside setState. A checkbox can represent an indeterminate value only when tristate is true. These controls do not automatically validate or save themselves through the text field’s Form contract.

NibSelect uses a controller for selection. Its value or values arguments seed an internally created controller; an external controller takes precedence. Supply exactly one of options or groups. Single selection reports T? through onChanged; onSelectionChanged reports List<T> in either mode. Multi-selection is a list of selected values, not a Set. Use the controller when a reset button elsewhere must clear the selection.

APITypeDefaultBehavior
NibCheckbox.valuebool?requiredCurrent value; null is indeterminate only with tristate.
NibSwitch.loadingboolfalseShows thumb progress and blocks interaction during an async change.
NibSelect.multiSelectboolfalseSelects one value or a list of values.
NibSelect.maxDropdownHeightdouble280Maximum menu height in logical pixels.

Keep drafts when submission fails

After local validation succeeds, mark the form busy and call your own save operation. Preserve the typed values until the operation succeeds. Display a field-specific server error through errorText and a general connection failure near the submit action. Clear an old server error when a relevant edit or a new response makes it obsolete; otherwise it continues to override a validator that now returns null.

A validator should answer whether the current value is valid. Avoid starting a request or changing State inside it: Flutter can invoke it repeatedly. Async validation belongs in the host submission flow or a separately managed check. A loading button prevents accidental repeated taps, but the service still needs its own duplicate-request policy.

Try adding a NibTextarea for a message. Its minimum is three lines; maxLength constrains length and showCounter controls whether the count is displayed. Use constraints that leave space for helper and error text. Test a long error at a narrow width before fixing the whole form to a short height. Reset only when the user asks or when successful submission clearly starts a fresh form.