OpenParable
Skip to content
← Back to skills

Handsontable Validator Dev

Development
handsontable-validator-dev

Handsontable Validator Dev is an Agent Skill for development published in the handsontable/handsontable repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Use when creating or modifying a Handsontable cell validator - async callback-based validation functions that determine if cell values are valid

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/handsontable/handsontable/blob/HEAD/.claude/skills/handsontable-validator-dev/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/handsontable-validator-dev, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Handsontable Validator Development

Function signature

Validators use the callback pattern and must always invoke the callback:

function myValidator(value, callback) {
  // `this` is bound to the cell's cellProperties object
  if (this.allowEmpty && (value === null || value === void 0 || value === '')) {
    return callback(true);
  }
  callback(isValid(value)); // true = valid, false = invalid
}

Key rules

  • Always call the callback. Forgetting to call callback hangs the validation pipeline.
  • Context-aware. this is the cell's cellProperties object. Use this.allowEmpty, this.instance (the Handsontable instance), and other cell meta properties.
  • Single responsibility. Validators only determine validity. Never modify data, DOM, or cell state.
  • Async-compatible. The callback can be called after async operations (API calls, timeouts). The editor enters WAITING state until the callback resolves.

File structure

src/validators/{validatorName}/
  {validatorName}.ts    # Validator function
  index.ts              # Re-exports

Registry: src/validators/registry.ts.

Registration

import { registerValidator } from '../../validators/registry';
registerValidator('myValidator', myValidator);

How validators are triggered

  • Automatically by the editor system during finishEditing().
  • Programmatically via validateCells(), validateRows(), or validateColumns() API methods.
  • Invalid cells receive the htInvalid CSS class (applied by the renderer pipeline, not the validator).

Reference implementations

  • src/validators/numericValidator/numericValidator.ts - Numeric validation with allowEmpty support.
  • src/validators/dateValidator/dateValidator.ts - Date format validation.
  • src/validators/autocompleteValidator/autocompleteValidator.ts - Validates against a list of allowed values.

Correcting cell values inside a validator

Validators may correct a cell's value before passing it to the callback. If your validator calls setDataAtCell to write a corrected value, pass a source string that ends with 'Validator' (e.g. 'myCustomValidator'):

this.instance.setDataAtCell(row, col, correctedValue, 'myCustomValidator');

This is required so that validateChanges() in core.js can track the correction and prevent it from being overwritten when an async validator in the same batch resolves later. Without the suffix, the correction is silently lost when the batch includes columns with async source callbacks (e.g. async autocomplete with strict: true).

Common mistakes

  • Forgetting to call callback, which silently blocks editing and validation.
  • Not respecting this.allowEmpty for empty values.
  • Calling setDataAtCell inside a validator without a source ending in 'Validator' - the correction will be overwritten when the batch contains async validators (see above).
  • Using arrow functions for the validator body (breaks this binding to cellProperties).