Validators

This section describes the available validation rules.

​

Empty values

A cell is empty when it is blank, contains only whitespace, is null, is an empty multi-select, or has no value at all (for example, its column wasn’t mapped). Empty cells are only checked by required and custom; every other validator, including the automatic ones for enum, reference, boolean, and date/time columns, skips them. To reject empty values, add required.

A custom validateFn receives empty cells as they are ('', whitespace, null, [], or undefined), so it can apply its own rules. If it throws, the cell is marked invalid, so either guard against empty values or set validatesEmptyValues: false to skip them. Rows that were added but never edited are not validated at all.

​

Async validators & run timing

Any validator may be synchronous or asynchronous. A custom validateFn (see custom) may return string | null | undefined or a Promise<string | null | undefined>, so you can validate against a remote service or an LLM.

By default, validators run reactively on every edit (runOn: 'change'). For slow or costly async checks, set runOn: 'submit' so the validator runs only in the final pass when the user submits — if it reports errors (and preventUploadOnValidationErrors is set), submission is blocked and the errors appear in the grid:

{
  validate: 'custom',
  key: 'verify_with_llm',
  runOn: 'submit', // deferred — runs once on submit, not on every edit
  validatesEmptyValues: false, // don't call the LLM for empty cells
  validateFn: async (value, row) => verifyWithLlm(value, row),
}

Async calls are throttled so a large sheet can’t fire one request per cell at once; tune the cap with maxConcurrentAsyncOperations. If an async validator rejects (e.g. a failed network/LLM call), the cell is marked invalid with the validator’s error message (or a default) rather than silently passing.

​

required

Description:
Ensures the field is not empty.

Additional:
Accepts an optional error message. Additionally, accepts a when function that returns a boolean value. If the function returns false, the validation is skipped. Defaults to () => true.

Example:

{
  "validate": "required",
  "when": (row) => row['employee.type'] === 'other'
}

---

​

unique

Description:
Ensures the value is unique across rows.

Additional:
Accepts an optional error message. Set caseInsensitive to true to compare string values case-insensitively. Empty cells are skipped, so several blank rows don’t count as duplicates.

---

​

regex_matches

Description:
Validates a field against a regular expression.

Additional:
Expects a regex and an optional error message.

---

​

includes

Description:
Checks if a value is within a predefined list.

Additional:
Requires a list of valid values.

---

​

multi_includes

Description:
Checks if all delimited values are valid.

Additional:
Accepts values, a delimiter, and an optional error message.

---

​

boolean

Description:
Ensures the value is a real boolean (true / false). Empty values pass; a value that couldn’t be coerced to a boolean (i.e. it matched neither the column’s true nor false tokens) fails.

Additional:
Added automatically to every boolean column, so you normally don’t configure it. You can also add it explicitly to provide a custom error message.

---

​

date

Description:
Ensures the value is a valid date / datetime / time and, optionally, within a configured range. Empty values pass; a value that couldn’t be parsed against the column’s format (or the ISO fallback) fails.

Additional:
Added automatically to every date, datetime, and time column, using that column’s outputFormat, displayFormat, min, and max, so you normally don’t configure it. Out-of-range values report a distinct error. You can also add it explicitly to provide a custom error message.

---

​

is_integer

Description:
Validates that the value is an integer.

Additional:
Optional error message.

---

​

phone_number

Description:
Validates phone number formatting.

Additional:
Optional error message.

---

​

email

Description:
Validates email format.

Pragmatic email validation based on: https://www.regular-expressions.info/email.html

• Case-insensitive
• Prevents consecutive dots in domain
• Intentionally not RFC 5322 complete

For more restrictive needs please use regex_matches validator.

Additional:
Optional error message.

---

​

postal_code

Description:
Validates postal code format.

Additional:
Optional error message.

---

​

custom

Description:
Custom validation function.

Additional:
Requires a key and a validateFn that returns an error message if validation fails. The validateFn may be synchronous or asynchronous — it may return a string | null | undefined or a Promise<string | null | undefined>. Set validatesEmptyValues: false to skip empty cells instead of passing them to validateFn (defaults to true, see Empty values).

Example (async):

{
  validate: 'custom',
  key: 'email_remote_check',
  validateFn: async (value) => {
    if (value && typeof value === 'string') {
      // simulate async check (e.g. remote service)
      const isEmailValid = await fetch('/api/validate-email', { method: 'POST', body: value });
      if(!isEmailValid) {
        return 'This email is too short';
      }
    }
    return undefined;
  },
}