Breadcrumbs

Custom Field Validation

Use custom validation when the built-in checks on a component's Validation tab (required, minimum and maximum length, pattern and so on) aren't enough. A custom validation script decides whether the value is acceptable and, if not, what message the user sees.

Add custom validation

  1. Open the component's settings and select the Validation tab.

  2. Expand Custom Validation and enter your script.

  3. Save the component.

The script must set the valid variable:

  • valid = true; accepts the value.

  • valid = 'Your message'; rejects it and shows the message under the component.

Custom validation also works on components inside a Data Grid; the message appears on the row with the problem.

Variables

Variable

Contains

input

The value entered in this component

data

The values of every component on the form, by property name

row

Inside a Data Grid or Edit Grid, the values of the current row

valid

Set this to true or to an error message

Custom validation also runs on the server

Custom validation runs in the browser as the user types, and again on the server when the form is submitted, so users can't get around it. On the server:

  • Only the variables above and standard JavaScript are available. Browser objects such as window, document and Formio don't exist. A script that uses them works in the browser but rejects every submission with an error such as ReferenceError: window is not defined.

  • A script must finish within 100 milliseconds. A slower script rejects the submission with Script execution timed out after 100ms.

When the server rejects a submission, the form shows the server's technical error response rather than a message under the field. Test your scripts so the browser check and the server check agree, and users only ever see the browser's message.

Examples

Limit the length of a text area

JavaScript
valid = (!input || input.length <= 250) ? true : 'Please enter 250 characters or fewer.';

For a simple length limit, you can also use Max Length on the Display tab without a script. See Text Area.

Match another field

Make sure a typed signature matches the employee's name entered elsewhere on the form:

JavaScript
valid = (input === data.employeeName) ? true : 'Please type your name as shown in the Employee Name field.';

Allow only a range of numbers

JavaScript
var amount = Number(input);
valid = (amount > 100 && amount < 500) ? true : 'Please enter a value between 100 and 500.';

Require a value in one of two fields

Put this on the second field, so the message appears when neither is filled in:

JavaScript
valid = (data.phone || input) ? true : 'Please enter a phone number or an email address.';

Tips

  • Check that values exist before you use them. If input is empty, calling input.length on it can cause an error.

  • Write messages that tell the user how to fix the problem.

  • Components with custom validation show an orange check-mark icon in the form builder. See Form Builder Tools.