Skip to content

Text cell type

Use the text cell type, the default cell type in Handsontable DataGrid, to display and edit plain text values.

Overview

The text cell type is the default cell type in Handsontable. It renders a cell’s value as plain text and lets you edit it with a standard text input. It has no built-in validator.

Because text is the default, you don’t need to set type: 'text' for it to apply. Set it explicitly when you want to override a different type inherited from a higher configuration level, or when you want the configuration to state the type directly, for example to guard alphanumeric codes or values with leading zeros against being reformatted by another type.

Vue
<script setup lang="ts">
import { ref } from 'vue';
import { HotTable } from '@handsontable/vue3';
import { registerAllModules } from 'handsontable/registry';
import type { GridSettings } from 'handsontable/settings';
// register Handsontable's modules
registerAllModules();
const hotSettings = ref<GridSettings>({
data: [
{ sku: '004821', category: '032', quantity: 142, unitPrice: 18.5 },
{ sku: '000093', category: '032', quantity: 0, unitPrice: 42.0 },
{ sku: '017640', category: '015', quantity: 67, unitPrice: 9.99 },
{ sku: '002210', category: '015', quantity: 310, unitPrice: 4.25 },
{ sku: '008875', category: '048', quantity: 24, unitPrice: 129.0 },
],
colHeaders: ['SKU', 'Category code', 'Quantity', 'Unit price ($)'],
height: 'auto',
autoWrapRow: true,
autoWrapCol: true,
columns: [
{ data: 'sku', type: 'text' },
{ data: 'category', type: 'text' },
{ data: 'quantity', type: 'numeric' },
{ data: 'unitPrice', type: 'numeric' },
],
// licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/
});
</script>
<template>
<div id="example1">
<HotTable :settings="hotSettings" />
</div>
</template>

In the example above, the sku and category columns use type: 'text' explicitly, even though it’s the default. This makes the configuration self-documenting: values such as '004821' are alphanumeric codes with leading zeros, not numbers, and the explicit type states that intent even if a later change sets a different type at the grid or column level.

Adding a validator

The text cell type ships without a built-in validator. To validate text values, combine type: 'text' with your own validator function, and set allowInvalid to false to reject invalid entries.

With allowInvalid: false, the cell editor doesn’t close on an invalid value. It stays open until you either enter a value that passes validation or press Esc to cancel the edit and restore the previous value. See invalid cell commit semantics for the full behavior, including how it differs from allowInvalid: true.

Vue
<script setup lang="ts">
import { ref } from 'vue';
import { HotTable } from '@handsontable/vue3';
import { registerAllModules } from 'handsontable/registry';
import type { GridSettings } from 'handsontable/settings';
// register Handsontable's modules
registerAllModules();
const skuValidator = (value: string, callback: (isValid: boolean) => void) => {
callback(/^\d{6}$/.test(value));
};
const hotSettings = ref<GridSettings>({
data: [
{ sku: '004821', supplier: 'Harbor Goods', quantity: 142 },
{ sku: '000093', supplier: 'Alpine Supply Co.', quantity: 0 },
{ sku: '017640', supplier: 'Harbor Goods', quantity: 67 },
{ sku: '002210', supplier: 'Crestline Wholesale', quantity: 310 },
{ sku: '008875', supplier: 'Alpine Supply Co.', quantity: 24 },
],
colHeaders: ['SKU', 'Supplier', 'Quantity'],
height: 'auto',
autoWrapRow: true,
autoWrapCol: true,
columns: [
{ data: 'sku', type: 'text', validator: skuValidator, allowInvalid: false },
{ data: 'supplier', type: 'text' },
{ data: 'quantity', type: 'numeric' },
],
// licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/
});
</script>
<template>
<div id="example2">
<HotTable :settings="hotSettings" />
</div>
</template>

Limiting the text length

To limit how many characters a text cell can hold, set the maxLength option. You don’t need a custom validator. By default, the length is not limited.

<HotTable :settings="{
columns: [
// a code of up to 10 characters
{ data: 'sku', type: 'text', maxLength: 10 },
// a comment of up to 140 characters, rejected when longer
{ data: 'comment', type: 'text', maxLength: 140, allowInvalid: false },
],
}" />

maxLength counts the characters a reader sees, in the same way as the length limit of a sheet name in the SheetsBar plugin. A flag, an emoji with a skin tone, and a letter with a combining accent each count as one character.

Handsontable applies the limit in two places:

  • In the cell editor. The text editor, and any custom editor that extends it, stops the user from typing or pasting more characters than the limit allows. A pasted text that doesn’t fit is cut at the limit. The editor never blocks deleting, so the user can shorten a value that is already too long, and typing into such a value doesn’t remove the text that is already there. The autocomplete, dropdown, and handsontable editors cap what the user types in the same way, but the user can still pick an option that is longer than the limit. The validator then marks the option as invalid, or rejects it when allowInvalid is false. The editors of the other cell types, such as numeric, date, and password, don’t limit input.
  • In validation. A value that is longer than the limit is invalid. Handsontable checks the values that the user types, pastes into the grid, or writes with setDataAtCell(), and the values that validateCells() checks. It doesn’t check the values that you load with loadData(), updateData(), or setSourceDataAtCell(), or that a data provider fetches. Call validateCells() to check them.

The allowInvalid option decides what happens to a value that is too long. With true (the default), the grid keeps the value and marks the cell with the htInvalid class. With false, the grid rejects the value, and the cell editor stays open until the value fits.

If a cell has both maxLength and a validator, the value must pass both checks. Handsontable checks the length first. When the value is too long, it doesn’t call your validator. Setting validator to false turns off the validator, but not the length check.

Limits and edge cases

  • Only strings are checked. Handsontable doesn’t check a value that is stored as a number, such as the digits typed into a numeric cell, or as any other non-string type.
  • Set the option on the free-text columns. The validator checks every string value in a cell that has a limit, whatever the cell type is. If you set maxLength at the grid level, it also applies to the text of date, time, dropdown, and autocomplete cells. With maxLength: 8, the date '2026-10-02' is invalid, and with allowInvalid: false, the grid rejects a dropdown option that is longer than the limit.
  • Validation is asynchronous. A cell that has a limit validates every write, as any cell with a validator does. setDataAtCell() applies the value after the validation finishes, and getDataAtCell() returns the previous value until then. Use the afterChange hook to react to the new value.
  • Spaces around the text don’t count. The editor and the validator both count the value after trimWhitespace is applied, so the leading and trailing spaces of a pasted text don’t use up the limit.
  • Formulas. With the Formulas plugin, the editor counts the formula that the user types, but the validator counts the calculated result. With maxLength: 5, the editor cuts =SUM(A1:A10) to =SUM(, although the result 55 fits. Set a limit on a column only if it holds no formulas.
  • An existing maxLength meta key. If your app already uses maxLength as a custom cell meta key, for example to feed your own validator or editor, the built-in check and the editor limit now apply to those cells too. See Migrating from 18.1 to 19.0.

Result

After configuring the text cell type, cells display and edit their value as plain text, with no formatting or masking applied. Combine it with maxLength to limit the text length, or with a custom validator to restrict which values a text cell accepts.

Keyboard shortcuts

The text cell editor uses the standard edition keyboard shortcuts. It has no type-specific key bindings.

Related guides

Configuration options

Core methods

Hooks