Table of Contents


Form validators that can be used directly via code or constructed from JSON to provide more dynamic validation.

Live Web Example

Using the library

Add the repo to your Flutter pubspec.yaml file.

  form_validation: <<version>> 

Then run...

flutter packages get


The library provides a set of built-in validators while also providing a mechanism for applications to provide their own validators. All the built-in validators are able to be deserialized via JSON. They all expect an attribute of type to match a specific value when being desearialized.

Note: With the sole exception of RequiredValidator, all built in validators will pass on null or empty values.

CurrencyValidatorcurrencyEnsures the value is a valid currency
EmailValidatoremailEnsures the value is a validly formatted email address
MaxLengthValidatormax_lengthEnsures the value contains no more than a set number of characters
MaxNumberValidatormax_numberEnsures the value is no larger than a given number
MinLengthValidatormin_lengthEnsures the value contains no fewer than a set number of characters
MinNumberValidatormin_numberEnsures the value is no smaller than a given number
NumberValidatornumberEnsures the value is a valid number
PhoneNumberValidatorphone_numberEnsures the value is a validly formatted phone number
RequiredValidatorrequiredEnsures the value is not null, empty, nor white space only

Validation Messages / Translations

The library provides a default set of English error messages for each validator's error message. This library uses the static_translations library for the string and language management, see it for details on how to override the defaults or provide values for other languages.

form_validation_currencylabelUsed when an invalid currency value is detected
form_validation_currency_positivelabelUsed when a valid, but negative, currency value is detected
form_validation_emaillabelUsed when an invalid email is detected
form_validation_max_lengthlabel, lengthUsed when a value contains more characters than length
form_validation_max_numberlabel, numberUsed when a value is larger than number
form_validation_min_lengthlabel, lengthUsed when a value contains fewer characters than length
form_validation_min_numberlabel, numberUsed when a value is smaller than number
form_validation_numberlabelUsed when a number is expected but not detected
form_validation_number_decimallabelUsed when a number is detected, but not allowed to be a decimal
form_validation_phone_numberlabelUsed when an invalid phone number is detected
form_validation_requiredlabelUsed when a value is required, but detected as null, empty, or all white space

JSON Support

The Validator class can be used to decode a list of child ValueValidator entries. Each of the built-in validators can be deserialized via JSON. In addition to being able to deserialize from JSON, each of the built-in validators supports serializing to a JSON compatible map via toJson or an actual JSON encoded string via toJsonString.

The overall struction needs to be:

  "validators": [
    // One or more of the JSON objects shown below


  "allowNegative": <bool>, // Default: true; states whether negative values are allowed or not
  "type": "currency"


  "type": "email"


  "length": <int>, // The maximum length the value may be
  "type": "max_length"


  "length": <int>, // The maximum number the value may be
  "type": "max_number"


  "length": <int>, // The minimum length the value may be
  "type": "min_length"


  "length": <int>, // The minimum number the value may be
  "type": "min_number"


  "type": "number"


  "type": "phone_number"


  "type": "required"

Custom Validators

The Validator supports custom validators being added either directly through classes extending the ValueValidator abstract class and passing them in via the constructor. Alternatively, an application may register a validator type with Validator using the registerCustomValidatorBuilder function.


class MyCustomValidator extends ValueValidator {
  static const type = 'my_custom_validator';

  static MyCustomValidator fromDynamic(dynamic map) {
      // initialization args go here

    MyCustomValidator result;

    if (map != null) {
      assert(map['type'] == type);

      result = MyCustomValidator(
        // Do additional JSON conversion here

    return result;

  Map<String, dynamic> toJson() => {
    // add additional attributes here
    "type": type,

  String validate({
    @required BuildContext context,
    @required String label,
    @required String value,
  }) {
    String error;

    // In general, validators should pass if the value is empty.  Combine 
    // validators with the RequiredValidator to ensure a value is non-empty.
    if (value?.isNotEmpty == true) {
      // Do processing to determine if the value is valid or not

    return error;


void main() {

  // start app


var jsonStr = '''
  "validators": [{
    "type": "required"
  }, {
    "type": "my_custom_validator"

// This will create a validation chain with the RequiredValidator as well as the
// MyCustomValidator defined above
var validator = Validator.fromDynamic(json.decode(jsonStr));