advanced_forms library

Flutter form validation and state management, built on ChangeNotifier and ValueListenable.

See the README.

Classes

AdvancedBooleanFieldController<E extends Object>
A specialization of AdvancedFieldController for a bool value.
AdvancedFieldBuilder<T, E extends Object>
Rebuilds whenever field notifies. Thin wrapper around ValueListenableBuilder that hides the <AdvancedFieldState<T, E>> type argument.
AdvancedFieldController<T, E extends Object>
A single form field which can be validated. T is the held value, E the error code; E cannot be nullable, so lack of an error is unambiguous.
AdvancedFieldState<T, E extends Object>
An immutable snapshot of an AdvancedFieldController. Obtain it from AdvancedFieldController.value, or listen to the controller for changes.
AdvancedFormController
A parent of multiple AdvancedFieldControllers. Manages group validation, tracks changes, and cleans up the resources it owns.
AdvancedFormState
The state of an AdvancedFormController — which fields and subforms it owns, whether the user has changed anything, and whether validation applies.
AdvancedMultiSelectFieldController<V, E extends Object>
A specialization of AdvancedFieldController for a multiple choice of V values.
AdvancedSingleSelectFieldController<V, E extends Object>
A specialization of AdvancedFieldController for a single choice of V from a list of options.
AdvancedTextFieldController<E extends Object>
A specialization of AdvancedFieldController for a String value.
AsyncValidation<T, E extends Object>
Everything a field needs to validate its value asynchronously.
AsyncValidationFailure
Diagnostic details of an async validation round that could not complete. Read it from AdvancedFieldController.lastFailure.

Enums

FieldStatus
The status of a AdvancedFieldController.
ValidationMode
When a field validates itself, with nobody calling validate().

Extensions

AdvancedFieldControllerListen on AdvancedFieldController<T, E>
Deprecated migration helper for AdvancedFieldController.
ValidatorCombinators on Validator<T, E>
Extension methods for Validator allowing to combine them.

Functions

and<T, E extends Object>(Iterable<Validator<T, E>> validators, [E? sharedMessage]) → Validator<T, E>
Each of the given validators has to accept input. If some accept, first error is returned or sharedMessage if provided.
atLeastLength<E extends Object>(int minLength, E message) → Validator<String?, E>
Rejects strings shorter than minLength.
boundedNonNegativeInteger<E extends Object>(int upperBound, E message) → Validator<String?, E>
Of the form >upperBound or num where num is between 0 and upperBound inclusive
conditionalValidator<T, E extends Object>(Validator<T, E> validator, bool enabledGetter()) → Validator<T, E>
If enabledGetter returns true validator is ran. Otherwise this accepts all input.
dynamicValidator<T, E extends Object>(Validator<T, E>? validatorBuilder()) → Validator<T, E>
Creates a new validator.
exactly<E extends Object>(String string, E message) → Validator<String?, E>
Requires to be exactly the given string.
filled<E extends Object>(E message) → Validator<String?, E>
Rejects null and empty strings (including whitespace only strings).
mustBeTrue<E extends Object>(E message) → Validator<bool?, E>
Rejects null and false.
nonNegativeDecimal<E extends Object>(E message) → Validator<String?, E>
Checks if the value is a decimal with a value above or equal to 0.
nonNegativeInteger<E extends Object>(E message) → Validator<String?, E>
Checks if the value is a integer with a value above or equal to 0.
notEmpty<T, E extends Object>(E message) → Validator<List<T>?, E>
Rejects null and empty lists
nothing<E extends Object>(E message) → Validator<String?, E>
Matches empty strings
notLongerThan<E extends Object>(int maxLength, E message) → Validator<String?, E>
Rejects strings longer than maxLength.
notNull<T, E extends Object>(E message) → Validator<T?, E>
Rejects null
or<T, E extends Object>(Iterable<Validator<T, E>> validators, [E? sharedMessage]) → Validator<T, E>
Only one of the given validators has to accept input. If none accept, first error is returned or sharedMessage if provided.
positiveDecimal<E extends Object>(E message) → Validator<String?, E>
Checks if the value is a decimal with a value above 0.
positiveInteger<E extends Object>(E message) → Validator<String?, E>
Checks if the value is a integer with a value above 0.

Typedefs

AsyncValidationFailureHandler = Future<void> Function(Object error, StackTrace stackTrace)
Handles a failure of an AsyncValidator — an exception it threw, or the TimeoutException of a round that ran out of time.
AsyncValidationFailureMapper<E extends Object> = E? Function(Object error, StackTrace stackTrace)
Maps a failure of an AsyncValidator to an error code, so a failed round can show something. Returning null leaves the field with no code; the status is FieldStatus.failedValidation either way.
AsyncValidator<T, E extends Object> = Future<E?> Function(T)
An async validate function receiving the current value and returning an error code. If null is returned, the value is considered valid.
ErrorTranslator<E extends Object> = String Function(E)
Translates an error to a string.
Validator<T, E extends Object> = E? Function(T)
A validate function receiving the current value and returning an error code. If null is returned, the value is considered valid.