How to Create Custom Validators in Retool Forms

Select a Text Input component inside your form. In the Inspector, scroll to the Validation section. Below the built-in rule toggles (Required, Min Length, Max Length, Pattern), you will find a Custom Validation field. Click the {{ fx }} icon to switch it to JavaScript expression mode. This field evaluates a JavaScript expression and expects the return value to be either an empty string '' (valid) or an error string (invalid). The error string is displayed as inline red text below the field.

Add two Text Input components inside the form: passwordInput (type: Password) and confirmPasswordInput (type: Password). On confirmPasswordInput, open the Validation section and enter this Custom Validation expression. The expression compares confirmPasswordInput's current value (self) against passwordInput.value and returns an error message if they differ. The self keyword refers to the current component's value in Custom Validation expressions.

1// Custom Validation on confirmPasswordInput:
2{{ self !== passwordInput.value ? 'Passwords do not match' : '' }}
3
4// With additional length check (combining with built-in Min Length):
5{{ self !== passwordInput.value ? 'Passwords do not match' : '' }}
6// Min Length: 8 (set as built-in rule — both rules must pass)

For a date range or budget allocation form, you may need to ensure one number is less than another. Add minValueInput and maxValueInput (Number Input components). On maxValueInput, add a Custom Validation expression that checks the relationship. This pattern works for any two-field comparison: start/end dates (using Date Pickers), minimum/maximum quantities, etc.

1// Custom Validation on maxValueInput:
2{{ self <= minValueInput.value ? 'Maximum must be greater than minimum' : '' }}
3
4// For date range validation on endDatePicker:
5{{ self && startDatePicker.value && new Date(self) <= new Date(startDatePicker.value) 
6   ? 'End date must be after start date' 
7   : '' }}
8
9// Budget allocation: sum of parts must not exceed total
10{{ (budgetQ1.value + budgetQ2.value + budgetQ3.value + budgetQ4.value) > totalBudgetInput.value
11   ? `Total allocation ${budgetQ1.value + budgetQ2.value + budgetQ3.value + budgetQ4.value} exceeds budget ${totalBudgetInput.value}`
12   : '' }}

For email or username uniqueness, load existing records with a query that runs on page load, then reference that query's data in the Custom Validation expression. Because Custom Validation expressions cannot trigger queries themselves, the uniqueness data must already be loaded. Create a query named getExistingEmails that returns a list of email records. On the emailInput, add a Custom Validation expression that checks whether the current value appears in that list.

1-- SQL query: getExistingEmails (Run on page load: ON)
2SELECT LOWER(email) as email FROM users;
3
4// Custom Validation on emailInput:
5{{ 
6  getExistingEmails.data.some(row => row.email === self.toLowerCase())
7    ? 'This email address is already registered'
8    : ''
9}}
10
11// For case-insensitive username check:
12{{ 
13  getExistingUsernames.data.some(row => row.username.toLowerCase() === self.toLowerCase())
14    ? 'Username already taken'
15    : ''
16}}

Custom Validation stacks on top of built-in rules — a field is only valid when all built-in rules AND the custom expression pass. For emailInput, you can have Required = true, Pattern = Email (built-in), and also the uniqueness custom validation. The field will show the most recently triggered error. Set the order of severity: the built-in Email pattern validation will prevent the uniqueness check from running on malformed input since Retool short-circuits on the first failing rule.

If a Custom Validation expression is not behaving as expected, open the Debug Panel at the bottom of the editor and click State Inspector. Find the component (e.g., emailInput) and expand its properties. You will see the current .value and .invalid state. You can also add a Text component to the canvas temporarily and set its Value to the raw expression to see what it returns: {{ getExistingEmails.data.some(row => row.email === emailInput.value.toLowerCase()) }}. This isolates whether the issue is the query data, the comparison logic, or the component reference.

1// Temporary debug Text component value:
2// Paste this to see the raw expression result
3{{ JSON.stringify(getExistingEmails.data.slice(0, 5)) }}
4
5// Check if the comparison logic is correct:
6{{ getExistingEmails.data.some(row => row.email === emailInput.value.toLowerCase()) }}

Custom validation integrates with form1.invalid automatically. Any component with a failing Custom Validation expression contributes to form1.invalid = true. Ensure the Submit button's Disabled property is set to {{ form1.invalid }} and optionally call form1.validate() at the start of the submit JS Query for defense-in-depth. The validate() call forces all error messages to display even if not yet touched.

1// JS Query: submitWithCustomValidation
2const isValid = form1.validate();
3
4if (!isValid) {
5  utils.showNotification({
6    title: 'Please fix the errors',
7    description: 'Check all highlighted fields before submitting.',
8    notificationType: 'warning',
9  });
10  return;
11}
12
13// Safe to submit — all built-in and custom validations passed
14await createUser.trigger({
15  additionalScope: {
16    email: emailInput.value,
17    username: usernameInput.value,
18    password: passwordInput.value,
19  }
20});
21
22form1.reset();