> ## Documentation Index
> Fetch the complete documentation index at: https://hellocsv.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`](#required) and
[`custom`](#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](#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:

```ts theme={null}
{
  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`](https://hellocsv.mintlify.site/v0.6.2/api-reference/importer-props). 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:

```ts theme={null}
{
  "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](https://hellocsv.mintlify.site/v0.6.2/api-reference/column-types.md#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](https://hellocsv.mintlify.site/v0.6.2/api-reference/column-types.md#date),
[datetime](https://hellocsv.mintlify.site/v0.6.2/api-reference/column-types.md#datetime), and
[time](https://hellocsv.mintlify.site/v0.6.2/api-reference/column-types.md#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](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](#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](#empty-values)).

Example (async):

```ts theme={null}
{
  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;
  },
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.