Custom validators in Flutter - Deep Dive

Overview - Custom validators

What is it?

Custom validators are functions you write to check if user input in a form meets specific rules you define. They help ensure data is correct before saving or sending it. Instead of using only built-in checks, you create your own rules for things like password strength or special formats. This makes your app smarter and safer.

Why it matters

Without custom validators, apps might accept wrong or harmful data, causing errors or security problems. Custom validators let you catch mistakes early, improving user experience and data quality. They help apps behave exactly how you want, making users trust your app more.

Where it fits

Before learning custom validators, you should know how to build basic forms and use simple built-in validators in Flutter. After mastering custom validators, you can learn about form state management and advanced input handling to build robust apps.

Mental Model

Core Idea

A custom validator is a small function that checks user input against your own rules and returns an error message if the input is invalid.

Think of it like...

It's like a security guard at a club who checks if each guest meets the dress code you set, allowing entry only if they do.

┌───────────────┐
│ User Input    │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Custom Validator ├─No error─► Accept Input
└──────┬────────┘
       │Error message
       ▼
┌───────────────┐
│ Show Error    │

Build-Up - 7 Steps

1

Foundation

Understanding basic validators

Concept: Learn what validators do in Flutter forms and how they check input.

In Flutter, a validator is a function that takes a string input and returns null if the input is valid or a string error message if invalid. For example, a simple validator checks if a field is empty and returns 'Please enter text' if it is.

Result

You can prevent form submission if the input is empty by showing an error message.

Understanding the basic validator function signature is key to creating your own rules.

2

Foundation

Using built-in validators

Concept: Explore Flutter's built-in validators like checking for empty fields or email format.

Flutter's TextFormField widget accepts a validator function. You can use simple checks like input.isEmpty or RegExp to validate emails. These built-in checks cover common cases but are limited.

Result

Forms can reject empty or badly formatted inputs automatically.

Knowing built-in validators helps you see when you need custom ones for special rules.

3

Intermediate

Writing your first custom validator

🤔Before reading on: do you think a custom validator must always return a string error message or can it return other types? Commit to your answer.

Concept: Create a validator function that checks a password length and returns a custom error message.

Define a function that takes a string and returns null if the password is at least 8 characters, else returns 'Password too short'. Assign this function to the validator property of a TextFormField.

Result

The form shows 'Password too short' if the user enters fewer than 8 characters.

Understanding that returning null means valid input is crucial for writing effective validators.

4

Intermediate

Combining multiple validation rules

🤔Before reading on: do you think you should write one validator per rule or combine all rules in one function? Commit to your answer.

Concept: Learn to combine several checks like length, special characters, and digits in one validator function.

Inside your validator, check each rule in order. Return the first error found or null if all pass. For example, check length, then presence of a digit, then special character.

Result

The user sees the first relevant error message, guiding them step-by-step to fix input.

Knowing how to combine rules in one validator improves user guidance and code clarity.

5

Intermediate

Using custom validators with FormState

Concept: Understand how validators integrate with Flutter's Form and FormState to control form submission.

Validators run when you call formKey.currentState!.validate(). If any validator returns an error, the form is invalid and submission stops. This lets you control when to accept or reject input.

Result

Form submission only proceeds if all validators return null.

Knowing how validators connect to form state helps you manage user input flow effectively.

6

Advanced

Creating reusable validator functions

🤔Before reading on: do you think writing validator functions inline or as separate reusable functions is better for large apps? Commit to your answer.

Concept: Learn to write validator functions that can be reused across multiple forms and fields.

Define validator functions as standalone functions or static methods that accept parameters like minimum length. This avoids repeating code and makes maintenance easier.

Result

You can apply the same validation logic consistently in many places by calling one function.

Understanding reusability reduces bugs and speeds up development in bigger projects.

7

Expert

Advanced validation with asynchronous checks

🤔Before reading on: do you think validators can perform asynchronous operations like server checks? Commit to your answer.

Concept: Explore how to handle validations that require waiting for external data, like checking if a username is taken.

Flutter's validator functions are synchronous, so for async checks, you must trigger them separately, e.g., on field change or form submit, and update UI accordingly. This often involves state management and showing loading indicators.

Result

You can validate inputs against server data, improving accuracy but requiring more complex code.

Knowing the limits of synchronous validators and how to handle async validation is key for real-world apps.

Under the Hood

Flutter validators are simple functions passed to form fields. When validate() is called on a FormState, Flutter runs each validator synchronously, collecting error messages. If any validator returns a non-null string, the form is invalid. The framework then displays these messages below the input fields automatically.

Why designed this way?

Validators are synchronous to keep UI responsive and simple. Asynchronous validation would complicate form state and user feedback. This design balances ease of use with performance, letting developers handle async cases separately.

┌───────────────┐
│ User Input    │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Validator Fn  │
│ (sync check)  │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ null or error │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ FormState     │
│ validate()    │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ UI updates    │
│ error display │
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: do you think returning an empty string from a validator means the input is valid? Commit yes or no.

Common Belief: Returning an empty string means no error, so the input is valid.

Reality: Only returning null means valid input; any string, even empty, is treated as an error message.

Why it matters: Returning an empty string causes the form to always show an error, confusing users and blocking submission.

Quick: do you think validators can run asynchronously inside the validator function? Commit yes or no.

Common Belief: Validators can perform async operations like API calls directly inside the validator function.

Reality: Validator functions must be synchronous; async checks require separate logic outside the validator.

Why it matters: Trying async inside validators causes runtime errors or ignored results, breaking validation.

Quick: do you think you must write a separate validator for every field even if rules are the same? Commit yes or no.

Common Belief: Each form field needs its own unique validator function, even if rules repeat.

Reality: You can write reusable validator functions and pass parameters to handle multiple fields efficiently.

Why it matters: Not reusing validators leads to duplicated code, harder maintenance, and inconsistent validation.

Quick: do you think validators run automatically as the user types? Commit yes or no.

Common Belief: Validators run live as the user types, showing errors immediately.

Reality: Validators run when validate() is called, usually on form submit or manually triggered, not automatically on every keystroke.

Why it matters: Expecting live validation without setup can confuse developers and users about when errors appear.

Expert Zone

1

Custom validators can be combined with Flutter's FocusNode and state management to create dynamic validation flows that react to user focus and input changes.

2

Validators should be pure functions without side effects to keep form behavior predictable and testable.

3

Handling localization in error messages inside validators requires careful design to avoid rebuilding validators unnecessarily.

When NOT to use

Avoid using custom validators for complex asynchronous checks like server-side uniqueness directly inside validator functions; instead, use separate async calls with state updates. Also, for very complex forms, consider dedicated form libraries that handle validation more robustly.

Production Patterns

In production, validators are often centralized in utility classes or services for reuse. Apps combine synchronous validators for immediate checks and asynchronous validation triggered on field blur or form submit. Error messages are localized and sometimes customized per user context.

Connections

State management in Flutter

Custom validators often work with state management to update UI based on validation results.

Understanding state management helps you trigger validation and show errors dynamically, improving user experience.

User experience design

Validation feedback is a key part of UX, guiding users to correct input errors smoothly.

Knowing UX principles helps you design validators that provide clear, timely, and helpful messages.

Quality assurance testing

Validators define rules that must be tested to ensure app reliability.

Understanding validators aids in writing test cases that cover edge cases and prevent bugs.

Common Pitfalls

#1 Returning empty string instead of null for valid input

Wrong approach:

String? validator(String? value) {
if (value == null || value.isEmpty) {
return 'Cannot be empty';
}
return ''; // wrong: empty string treated as error
}

Correct approach:

String? validator(String? value) {
if (value == null || value.isEmpty) {
return 'Cannot be empty';
}
return null; // correct: null means valid
}

Root cause:

Misunderstanding that only null means valid input in Flutter validators.

#2 Trying to perform async validation inside validator

Wrong approach:

String? validator(String? value) async {
bool available = await checkUsername(value!);
if (!available) return 'Username taken';
return null;
}

Correct approach:

String? validator(String? value) {
// synchronous checks only
if (value == null || value.isEmpty) return 'Required';
return null;
}

// Perform async check separately and update UI state

Root cause:

Validator functions must be synchronous; async code breaks validation flow.

#3 Duplicating validator code for similar fields

Wrong approach:

TextFormField(validator: (v) => v!.length < 8 ? 'Too short' : null),
TextFormField(validator: (v) => v!.length < 8 ? 'Too short' : null),

Correct approach:

String? minLengthValidator(String? v, int min) => v != null && v.length >= min ? null : 'Too short';

TextFormField(validator: (v) => minLengthValidator(v, 8)),
TextFormField(validator: (v) => minLengthValidator(v, 8)),

Root cause:

Not abstracting common validation logic leads to repeated code and harder maintenance.

Key Takeaways

Custom validators are functions that check user input and return error messages or null for valid input.

Validators in Flutter must be synchronous and return null to indicate valid input; any string means an error.

Writing reusable validator functions improves code quality and consistency across your app.

Asynchronous validation requires separate handling outside the validator function to keep UI responsive.

Understanding how validators connect with form state and user experience is key to building reliable, user-friendly forms.