NIB / DOCUMENTATION
Forms and state — NibComponents
Validate text, choose values, and keep input ownership clear.
Open interactive viewPut 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),
]),
);| API | Type | Default | Behavior |
|---|---|---|---|
| controller | TextEditingController? | null | External text owner; mutually exclusive with initialValue. |
| initialValue | String? | null | Seeds an internally owned controller. |
| validator | NibValidator? | null | Returns an error string or null; Form.validate invokes it. |
| autovalidateMode | AutovalidateMode | onUserInteraction | Controls when the validator runs before explicit Form validation. |
| errorText | String? | null | Forced error that takes precedence over validator output and helper text. |
| minHeight | double? | null | Optional 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.
| API | Type | Default | Behavior |
|---|---|---|---|
| NibValidators.required() | NibValidator | default message | Rejects null, empty, and whitespace-only text. |
| NibValidators.email() | NibValidator | default message | Checks a non-empty email-shaped value. |
| NibTextarea.minLines | int | 3 | Initial minimum visible text lines. |
| NibTextarea.showCounter | bool | false | Shows 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.
| API | Type | Default | Behavior |
|---|---|---|---|
| NibCheckbox.value | bool? | required | Current value; null is indeterminate only with tristate. |
| NibSwitch.loading | bool | false | Shows thumb progress and blocks interaction during an async change. |
| NibSelect.multiSelect | bool | false | Selects one value or a list of values. |
| NibSelect.maxDropdownHeight | double | 280 | Maximum 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.