Cell validator

Cell validators run when a user finishes editing a cell. Use them to enforce data rules such as required fields, numeric ranges, or pattern matching.

Overview

When you create a validator, assign it an alias so you can reference it by name in column configuration. Handsontable defines 5 aliases by default:

autocomplete for Handsontable.validators.AutocompleteValidator
date for Handsontable.validators.DateValidator
dropdown for Handsontable.validators.DropdownValidator
numeric for Handsontable.validators.NumericValidator
time for Handsontable.validators.TimeValidator

Aliases give you a convenient way to specify which validator runs when table validation triggers. You don’t need to reference the validator function directly, and you can swap the function behind an alias without changing your column configuration.

Register custom cell validator

To register your own alias use Handsontable.validators.registerValidator() function. It takes two arguments:

validatorName - a string representing a validator function
validator - a validator function that will be represented by validatorName

If you’d like to register creditCardValidator under alias credit-card you have to call:

1
Handsontable.validators.registerValidator('credit-card', creditCardValidator);

Choose aliases wisely. If you register your validator under name that is already registered, the target function will be overwritten:

1
Handsontable.validators.registerValidator('date', creditCardValidator);

Now ‘date’ alias points to creditCardValidator function, not Handsontable.validators.DateValidator.

So, unless you intentionally want to overwrite an existing alias, try to choose a unique name. A good practice is prefixing your aliases with some custom name (for example your GitHub username) to minimize the possibility of name collisions. This is especially important if you want to publish your validator, because you never know aliases has been registered by the user who uses your validator.

1
Handsontable.validators.registerValidator('credit-card', creditCardValidator);

Someone might already registered such alias.

1
Handsontable.validators.registerValidator('my.credit-card', creditCardValidator);

That’s better.

Using an alias

The final touch is to use the registered aliases, so that you can easily refer to them without knowing the actual validator function.

To sum up, a well prepared validator function should look like this:

1
(Handsontable => {
2
  function customValidator(query, callback) {
3
    // ...your custom logic of the validator
4

5
    callback(/* Pass `true` or `false` based on your logic */);
6
  }
7

8
  // Register an alias
9
  Handsontable.validators.registerValidator('my.custom', customValidator);
10

11
})(Handsontable);

From now on, you can use customValidator like so:

1
const container = document.querySelector('#container')
2
const hot = new Handsontable(container, {
3
  columns: [{
4
    validator: 'my.custom'
5
  }]
6
});

Full featured example

Use the validator method to easily validate synchronous or asynchronous changes to a cell. If you need more control, beforeValidate and afterValidate hooks are available. In the below example, email_validator_fn is an async validator that resolves after 1000 ms.

Use the allowInvalid option to define if the grid should accept input that does not validate. If you need to modify the input (e.g., censor bad words, uppercase first letter), use the plugin hook beforeChange.

By default, all invalid cells are marked by htInvalid CSS class. If you want to change class to another you can basically add the invalidCellClassName option to Handsontable settings. For example:

For the entire table

1
invalidCellClassName: 'myInvalidClass'

For specific columns

1
columns: [
2
  { data: 'firstName', invalidCellClassName: 'myInvalidClass' },
3
  { data: 'lastName', invalidCellClassName: 'myInvalidSecondClass' },
4
  { data: 'address' }
5
]

Callback console log:

Here you will see the log

1
import Handsontable from 'handsontable/base';
2
import { registerAllModules } from 'handsontable/registry';
3

4
// Register all Handsontable's modules.
5
registerAllModules();
6

7
const container = document.querySelector('#example1');
8
const output = document.querySelector('#output');
9
const ipValidatorRegexp =
10
  /^(?:\b(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\b|null)$/;
11

12
const emailValidator = (value, callback) => {
13
  setTimeout(() => {
14
    if (/.+@.+/.test(value)) {
15
      callback(true);
16
    } else {
17
      callback(false);
18
    }
19
  }, 1000);
20
};
21

22
new Handsontable(container, {
23
  data: [
66 collapsed lines
24
    {
25
      id: 1,
26
      name: { first: 'Joe', last: 'Fabiano' },
27
      ip: '0.0.0.1',
28
      email: 'Joe.Fabiano@ex.com',
29
    },
30
    {
31
      id: 2,
32
      name: { first: 'Fred', last: 'Wecler' },
33
      ip: '0.0.0.1',
34
      email: 'Fred.Wecler@ex.com',
35
    },
36
    {
37
      id: 3,
38
      name: { first: 'Steve', last: 'Wilson' },
39
      ip: '0.0.0.1',
40
      email: 'Steve.Wilson@ex.com',
41
    },
42
    {
43
      id: 4,
44
      name: { first: 'Maria', last: 'Fernandez' },
45
      ip: '0.0.0.1',
46
      email: 'M.Fernandez@ex.com',
47
    },
48
    {
49
      id: 5,
50
      name: { first: 'Pierre', last: 'Barbault' },
51
      ip: '0.0.0.1',
52
      email: 'Pierre.Barbault@ex.com',
53
    },
54
    {
55
      id: 6,
56
      name: { first: 'Nancy', last: 'Moore' },
57
      ip: '0.0.0.1',
58
      email: 'Nancy.Moore@ex.com',
59
    },
60
    {
61
      id: 7,
62
      name: { first: 'Barbara', last: 'MacDonald' },
63
      ip: '0.0.0.1',
64
      email: 'B.MacDonald@ex.com',
65
    },
66
    {
67
      id: 8,
68
      name: { first: 'Wilma', last: 'Williams' },
69
      ip: '0.0.0.1',
70
      email: 'Wilma.Williams@ex.com',
71
    },
72
    {
73
      id: 9,
74
      name: { first: 'Sasha', last: 'Silver' },
75
      ip: '0.0.0.1',
76
      email: 'Sasha.Silver@ex.com',
77
    },
78
    {
79
      id: 10,
80
      name: { first: 'Don', last: 'Pérignon' },
81
      ip: '0.0.0.1',
82
      email: 'Don.Pérignon@ex.com',
83
    },
84
    {
85
      id: 11,
86
      name: { first: 'Aaron', last: 'Kinley' },
87
      ip: '0.0.0.1',
88
      email: 'Aaron.Kinley@ex.com',
89
    },
90
  ],
91
  beforeChange(changes) {
92
    for (let i = changes.length - 1; i >= 0; i--) {
93
      const currChange = changes[i];
94

95
      if (!currChange) {
96
        return false;
97
      }
98

99
      // gently don't accept the word "foo" (remove the change at index i)
100
      if (currChange[3] === 'foo') {
101
        changes.splice(i, 1);
102
      }
103
      // if any of pasted cells contains the word "nuke", reject the whole paste
104
      else if (currChange[3] === 'nuke') {
105
        return false;
106
      }
107
      // capitalise first letter in column 1 and 2
108
      else if (currChange[1] === 'name.first' || currChange[1] === 'name.last') {
109
        if (currChange[3] !== null) {
110
          changes[i][3] = currChange[3].charAt(0).toUpperCase() + currChange[3].slice(1);
111
        }
112
      }
113
    }
114

115
    return true;
116
  },
117
  afterChange(changes, source) {
118
    if (source !== 'loadData') {
119
      output.innerText = JSON.stringify(changes);
120
    }
121
  },
122
  colHeaders: ['ID', 'First name', 'Last name', 'IP', 'E-mail'],
123
  height: 'auto',
124
  licenseKey: 'non-commercial-and-evaluation',
125
  columns: [
126
    { data: 'id', type: 'numeric' },
127
    { data: 'name.first' },
128
    { data: 'name.last' },
129
    { data: 'ip', validator: ipValidatorRegexp, allowInvalid: true },
130
    { data: 'email', validator: emailValidator },
131
  ],
132
  autoWrapRow: true,
133
  autoWrapCol: true,
134
});

1
import Handsontable from 'handsontable/base';
2
import { registerAllModules } from 'handsontable/registry';
3

4
// Register all Handsontable's modules.
5
registerAllModules();
6

7
const container = document.querySelector('#example1')!;
8
const output = document.querySelector('#output') as HTMLElement;
9

10
const ipValidatorRegexp =
11
  /^(?:\b(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\b|null)$/;
12

13
const emailValidator = (value: string, callback: (value: boolean) => void) => {
14
  setTimeout(() => {
15
    if (/.+@.+/.test(value)) {
16
      callback(true);
17
    } else {
18
      callback(false);
19
    }
20
  }, 1000);
21
};
22

23
new Handsontable(container, {
24
  data: [
66 collapsed lines
25
    {
26
      id: 1,
27
      name: { first: 'Joe', last: 'Fabiano' },
28
      ip: '0.0.0.1',
29
      email: 'Joe.Fabiano@ex.com',
30
    },
31
    {
32
      id: 2,
33
      name: { first: 'Fred', last: 'Wecler' },
34
      ip: '0.0.0.1',
35
      email: 'Fred.Wecler@ex.com',
36
    },
37
    {
38
      id: 3,
39
      name: { first: 'Steve', last: 'Wilson' },
40
      ip: '0.0.0.1',
41
      email: 'Steve.Wilson@ex.com',
42
    },
43
    {
44
      id: 4,
45
      name: { first: 'Maria', last: 'Fernandez' },
46
      ip: '0.0.0.1',
47
      email: 'M.Fernandez@ex.com',
48
    },
49
    {
50
      id: 5,
51
      name: { first: 'Pierre', last: 'Barbault' },
52
      ip: '0.0.0.1',
53
      email: 'Pierre.Barbault@ex.com',
54
    },
55
    {
56
      id: 6,
57
      name: { first: 'Nancy', last: 'Moore' },
58
      ip: '0.0.0.1',
59
      email: 'Nancy.Moore@ex.com',
60
    },
61
    {
62
      id: 7,
63
      name: { first: 'Barbara', last: 'MacDonald' },
64
      ip: '0.0.0.1',
65
      email: 'B.MacDonald@ex.com',
66
    },
67
    {
68
      id: 8,
69
      name: { first: 'Wilma', last: 'Williams' },
70
      ip: '0.0.0.1',
71
      email: 'Wilma.Williams@ex.com',
72
    },
73
    {
74
      id: 9,
75
      name: { first: 'Sasha', last: 'Silver' },
76
      ip: '0.0.0.1',
77
      email: 'Sasha.Silver@ex.com',
78
    },
79
    {
80
      id: 10,
81
      name: { first: 'Don', last: 'Pérignon' },
82
      ip: '0.0.0.1',
83
      email: 'Don.Pérignon@ex.com',
84
    },
85
    {
86
      id: 11,
87
      name: { first: 'Aaron', last: 'Kinley' },
88
      ip: '0.0.0.1',
89
      email: 'Aaron.Kinley@ex.com',
90
    },
91
  ],
92
  beforeChange(changes) {
93
    for (let i = changes.length - 1; i >= 0; i--) {
94
      const currChange = changes[i];
95

96
      if (!currChange) {
97
        return false;
98
      }
99

100
      // gently don't accept the word "foo" (remove the change at index i)
101
      if (currChange[3] === 'foo') {
102
        changes.splice(i, 1);
103
      }
104
      // if any of pasted cells contains the word "nuke", reject the whole paste
105
      else if (currChange[3] === 'nuke') {
106
        return false;
107
      }
108
      // capitalise first letter in column 1 and 2
109
      else if (currChange[1] === 'name.first' || currChange[1] === 'name.last') {
110
        if (currChange[3] !== null) {
111
          changes[i]![3] = currChange[3].charAt(0).toUpperCase() + currChange[3].slice(1);
112
        }
113
      }
114
    }
115

116
    return true;
117
  },
118
  afterChange(changes, source) {
119
    if (source !== 'loadData') {
120
      output.innerText = JSON.stringify(changes);
121
    }
122
  },
123
  colHeaders: ['ID', 'First name', 'Last name', 'IP', 'E-mail'],
124
  height: 'auto',
125
  licenseKey: 'non-commercial-and-evaluation',
126
  columns: [
127
    { data: 'id', type: 'numeric' },
128
    { data: 'name.first' },
129
    { data: 'name.last' },
130
    { data: 'ip', validator: ipValidatorRegexp, allowInvalid: true },
131
    { data: 'email', validator: emailValidator },
132
  ],
133
  autoWrapRow: true,
134
  autoWrapCol: true,
135
});

1
<output class="console" id="output">Here you will see the log</output>
2
<div id="example1"></div>

Edit the above grid to see the changes argument from the callback.

Mind that changes in table are applied after running all validators (both synchronous and and asynchronous) from every changed cell.

APIs

BasePlugin

Configuration options

Core methods

Hooks

Result

You now have a cell validator that enforces data rules when a user finishes editing. Register it under an alias to reference it by name across your column configuration, and use allowInvalid: false to keep the editor open until the user enters a valid value.