Data Validation

Overview
Validation Mode
Validator Functions
Highlight Validation
Manual Validation
Callbacks

Overview

Validation functionality is provided by the validate module

Validators are used to ensure that any user input into your editable cells matches your requirements.

Validators can be applied by using the validator property in a columns definition object (see Define Columns for more details).

{title:"Rating", field:"rating", editor:"input", validator:"required"}

When using validators that take properties you can pass in an object:

{title:"Rating", field:"rating", editor:"input", validator:{
	type:"max",
	parameters:5,
}}

Or you can use the shorthand notation, separating the type and parameter with a : symbol:

{title:"Rating", field:"rating", editor:"input", validator:"max:5"}

Validation Mode

There are three different validation modes available to customise the validation experience:

blocking - if a user enters an invalid value while editing, they are blocked from leaving the cell until a valid value is entered (default)
highlight - if a user enters an invalid value, then the edit will complete as usual and they are allowed to exit the cell but a highlight is applied to the cell using the tabulator-validation-fail class
manual - no vaildation is automatically performed on edit, but it can be triggered by calling the validate function on the table or any Component Object

The validation mode can be set using the validationMode setup option:

var table = new Tabulator("#example-table", {
    validationMode:"highlight", //highlight cells with validation errors but don't stop the edit
});

Validator Functions

Built In Validators

Tabulator has a wide variety of built in validators:

Note: For a guide to adding your own validators to this list, have a look at the Extending Tabulator section.

Note By default all validators, except the required validator will approve any empty value (ie. empty string, null or undefined). to ensure empty values are rejected you should use the required validator.

Required

The required validator allows values that are not null or an empty string

{title:"Example", field:"example", validator:"required"}

Unique

The unique validator allows values that do not match the value of any other cell in this column

{title:"Example", field:"example", validator:"unique"}

Integer

The integer validator allows values that are valid integers

{title:"Example", field:"example", validator:"integer"}

Float

The float validator allows values that are valid floats

{title:"Example", field:"example", validator:"float"}

Numeric

The numeric validator allows values that are valid numbers

{title:"Example", field:"example", validator:"numeric"}

String

The string validator allows values that are a non-numeric string

{title:"Example", field:"example", validator:"string"}

Alphanumeric

The alphanumeric validator allows values that are explicitly numbers and letters with no symbols or spaces

{title:"Example", field:"example", validator:"alphanumeric"}

Minimum Numeric Value

The min validator allows numeric values that are greater than or equal to parameter

 {title:"Example", field:"example", validator:"min:5"} \\value must be greater than or equal to 5

Maximum Numeric Value

The max validator allows numeric values that are less than or equal to parameter

 {title:"Example", field:"example", validator:"max:5"} \\value must be less than or equal to 5

Minimum String Length

The minLength validator allows string values that have a length greater than or equal to parameter

 {title:"minLength", field:"example", validator:"minLength:5"} \\value must have a length greater than or equal to 5

Maximum String Length

The maxLength validator allows string values that have a length less than or equal to parameter

 {title:"Example", field:"example", validator:"maxLength:5"} \\value must have a length less than or equal to 5

In List

The in validator allows values that match a value from the | delimited string in the parameter

 {title:"Example", field:"example", validator:"in:red|green|blue"} \\value must be 'red', 'green' or 'blue'

Starts With

The starts validator allows string values that start with the parameter (case insensitive)

 {title:"Example", field:"example", validator:"starts:bob"} \\value must start with 'bob'

Ends With

The ends validator allows string values that start with the parameter (case insensitive)

 {title:"Example", field:"example", validator:"ends:green"} \\value must end with 'green'

Regular Expression

The regex validator allows values that match the supplied regex

 {title:"Example", field:"example", validator:"regex:\\.com$"} \\allow strings that end in '.com'

Validation Failure

If the validation fails the tabulator-validation-fail class will be applied to the cell and the validationFailed callback will be triggered.

The user will not be able to leave the a cell that has failed vailidation until they input a valid value or cancel the edit (press escape)

Custom Validator Functions

If you want to add your own custom validation functions, you can pass a function to the validator property. It should return true if the value passes validation and false if it fails:

//validator to prevent values divisible by the provided divisor
var noDivide = function(cell, value, parameters){
	//cell - the cell component for the edited cell
	//value - the new input value of the cell
	//parameters - the parameters passed in with the validator

	return value % parameters.divisor; //don't allow values divisible by divisor ;
}

//in your column definition for the column
{title:"Age", field:"age", editor:"input", validator:[
	{
		type:noDivide,
		parameters:{
			divisor:5,
		}
	}
]}

Applying Multiple Validators

You can use multiple validators on the same column by passing an array to the validator property

{title:"Rating", field:"rating", editor:"input", validator:["required", "max:5"]}

Highlight Validation

If you are using the highlight validation mode then Tabulator provides a variety of ways to check the validation state of different cells in the table.

Retrieve Invalid Cells

The getInvalidCells method returns an array of Cell Components for all cells flagged as invalid after a user edit.

var invalid = table.getInvalidCells();

Tabulator will continue to add cells to this list until the table in the data is replaced by the setData function or the invalid list is cleared.

Check Cell as Passed Validation

The isValid can be called on a Cell Component to check if a cell has previously passed a validation check without revalidating it.

var valid = cell.isValid();

This will return a value of true if the cell passes validation, or an array of failed validators if it fails validation.

The failed validation array contains validator objects for each validator that has failed. each object has a type prop which is the key for that validator (eg. "required"), and parameters prop which contains any props passed with the validator

In the example below, the validation failed on the min validator with its parameter set to 5:

[
    {
        key:"min"
        parameters:5,
    }
]

This function is different from the validate function which actively validates the cell, the isValid function only checks to see if a user has edited the cell and that it has passed validation when that happened

Clear Invalid Validation

You can clear the invalid validation state of a cell in a couple of ways.

The clearValidation can be called on a Cell Component to clear the invalid flag used by the isValid function and mark the cell as valid.

cell.clearValidation();

Alternativly, the clearCellValidation can be called on the table to clear the invalid state on all cells in the table

table.clearCellValidation();

Or optionally you can pass in a Cell Component or an array of Cell Components to the clearCellValidation function to clear the invalid state on specific cells

table.clearCellValidation([cell1, cell2]);

Manual Validation

If you are using the manual validation mode then Tabulator provides a variety of ways to trigger validation of the table.

Table Validation

You can validate the whole table in one go by calling the validate method on the table instance.

var valid = table.validate();

This will return a value of true if every cell passes validation, if any cells fail, then it will return an array of Cell Components representing each cell that has failed validation.

Row Validation

You can validate a row by calling the validate method on any Row Component

var valid = row.validate();

This will return a value of true if every cell passes validation, if any cells fail, then it will return an array of Cell Components representing each cell in that row that has failed validation.

Column Validation

You can validate a column by calling the validate method on any Column Component

var valid = column.validate();

This will return a value of true if every cell passes validation, if any cells fail, then it will return an array of Cell Components representing each cell in that column that has failed validation.

Cell Validation

You can validate a cell by calling the validate method on any Cell Component

var valid = cell.validate();