formx 0.11.0

Access, build, validate, sanitize and fill forms easily with Formx.

Formx

Acessing the state

BuildContext.formx([String? key]) automatically retrieves the appropriate FormState for you, though you can specify a key if necessary.

final state = context.formx();
final addressState = context.formx('address');

final email = context.field('email').value;

Alternatively, use Formx.of(context) for a traditional approach without visitors, which also rebuilds the widget on form state changes, similar to Form.of(context).

FormState extensions

• .value<T>(String key), gets the [FormFieldState.value] of a specific field.
• .values, a structured Map with all the values of the form.
• .initialValues, a structured Map with all the initial values of the form.
• .hasInteractedByUser, whether any nested [FormFieldState.hasInteractedByUser].
• .hasError, whether any nested [FormFieldState.hasError].
• .isValid, whether all nested [FormFieldState.isValid].
• .errorTexts, a flat Map with all nested [FormFieldState.errorText].
• operator [key], operator to get a specific [FormFieldState] by it's key value.
• operator [key] = value, operator to set any nested form/field value(s) directly.

FormxState extension type

FormxState is an inline-class that redeclares some of the FormState methods:

• .validate([List<String>? keys])
• .save([List<String>? keys])
• .reset([List<String>? keys])

These methods function identically to their original counterparts but extend their effects to nested forms. Using FormState.validate only validates the top-level form, whereas FormxState.validate also validates any nested forms.

You have the option to specify a list of keys with these methods to target specific forms or fields for validation, saving, or resetting.

You can redeclare any FormState to a FormxState by using FormxState(formState) type extension.

FormFieldState extensions

• .setErrorText(String? errorText), sets the field errorText programmatically. Requires Validator.

Validator class

Looking for a way to create validators declaratively? The Validator class provides a readable and declarative approach to defining validation rules for your Dart applications.

TextFormField(
  validator: Validator<String>(
    isRequired: true,
    test: (value) => value.isEmail,
  ),
),

For the one-liners, the modifiers allows you to chain your validators.

TextFormField(
  validator: Validator().required().email(),
),

You can also easily create custom validators:

extension CustomValidators on Validator<T> {
  Validator<T> myValidator([String? requiredText]) {
    return test((value) => /* your logic here */, requiredText);
  }
}

Customizing

// You can set a default `requiredText`/`invalidText` for all validators:
Validator.defaultRequiredText = 'This field is required';
Validator.defaultInvalidText = 'This field is invalid';

// You can also modify the errorText of a validator:
Validator.modifier = (validator, errorText) => errorText; // good for translations

// And disable them all:
Validator.disableOnDebug = true; // only works on debug mode

Modifiers

• .test(bool Function(T value) test)
• .number(bool Function(num value) test)
• .datetime(bool Function(DateTime value) test)
• .required
• .email
• .url
• .phone
• .creditCard
• .cpf
• .cnpj
• .date
• .alpha
• .numeric
• .alphanumeric
• .hasAlpha
• .hasNumeric
• .hasAlphanumeric
• .hasUppercase
• .hasLowercase
• .hasSpecialCharacter
• .minLength(int length)
• .maxLength(int length)
• .minWords(int words)
• .maxWords(int words)
• .minNumber(num number)
• .maxNumber(num number)
• .isAfter(DateTime date)
• .isBefore(DateTime date)

Validators, Sanitizers & Helpers extensions

Formx comes bundled with a set of built-in validators and sanitizers, which you can use to validate and sanitize your form fields.

String

• .isEmail
• .isPhone
• .isUrl
• .isDate
• .isCreditCard
• .isCpf
• .isCnpj
• .isNumeric
• .isAlpha
• .isAlphanumeric
• .hasAlpha
• .hasNumeric
• .hasAlphanumeric
• .hasUppercase
• .hasLowercase
• .hasSpecialCharacters
• .equalsIgnoreCase(String)
• .onlyNumeric (removes all non-numeric characters)
• .onlyAlpha (removes all non-alphabetic characters)
• .onlyAlphanumeric (removes all non-alphanumeric characters)

Map

• .indented for a map view that indents when printed.
• .indentedText for getting an indented text.
• .deepMap for mapping nested maps.
• .clean for values that are null or empty string/iterable/map.
• .cleaned for a new map with all null or empty values removed.

Deeply recases all your map keys:

• .camelCase "camelCase"
• .constantCase "CONSTANT_CASE"
• .sentenceCase "Sentence case"
• .snakeCase "snake_case"
• .dotCase "dot.case"
• .paramCase "param-case"
• .pathCase "path/case"
• .pascalCase "PascalCase"
• .headerCase "Header-Case"
• .titleCase "Title Case"

List<Widget>

• .keepAlive usually needed for building forms with [PageView.children].
• .expanded usually needed for building forms with [Column.children] or [Row.children].

Contributing

Contributions to formx are welcome! Whether it's bug reports, feature requests, or pull requests, all "forms" of collaboration can help make formx better for everyone.