Masked text editor

Use ColumnMasked for fixed-shape strings, such as identifiers and phone numbers. A masked identifier that contains only digits is still text: leading zeros and separators can be meaningful. For decimal arithmetic, use the number editor instead.

1. Register a fixed mask

Use the grid element from Number setup:

import { ColumnMasked } from '@revolist/revogrid-pro';

grid.applyOnClose = true; // Save valid drafts when leaving the cell.
grid.columnTypes = { masked: ColumnMasked };
grid.columns = [{
  prop: 'code', name: 'Code', columnType: 'masked',
  maskedEditor: {
    mask: '00-000', store: 'raw', required: true,
    label: 'Code',
  },
}];
grid.source = [{ code: '00012' }];

The column displays 00-012. Double-click to edit. The empty editor shows __-___: underscores mark editable slots and the hyphen stays visible. Typing fills the active slots, skips the hyphen, and produces 00-012 from 00012. You can also paste a complete raw value (00012) or formatted value (00-012). Enter, Tab, or leaving the cell saves a valid draft. Escape cancels the edit. Incomplete values cannot save. Keystrokes and pastes that do not fit the mask leave the current draft unchanged.

2. Choose mask tokens

Token	Accepts	Example mask
0	ASCII digit (0–9)	00-000
A	ASCII letter (A–Z, a–z)	AA-0000
*	ASCII letter or digit	***-000
Other characters	Literal separator	Parentheses, spaces, hyphens, dots
Backslash	Escapes the next character as a literal	\\A-000 in a JavaScript string

JavaScript strings need two backslashes to encode one mask escape. For example, mask: '\\A-000' means a literal A, a literal hyphen, and three digits. Its raw value 001 displays A-001.

All token positions must be filled. This is a fixed mask, not a regular expression, a variable-length phone-number parser, or a numeric formatting pattern.

The in-cell editor always shows the full mask with _ for unfilled slots. Typing overwrites the active slot and the caret skips literal separators. Backspace and Delete clear a slot without shifting the remaining characters. Selecting part of the value clears its editable slots and lets you replace them without changing separators. Pasting accepts raw or formatted text and rejects incompatible pastes as a whole. Ctrl/Cmd+Z undoes draft edits; Ctrl/Cmd+Shift+Z or Ctrl+Y redoes them. Incomplete drafts stay neutral while you type; Enter or Tab shows validation feedback and keeps an incomplete editor open. Leaving an incomplete draft does not save it. Invalid source values still show validation feedback when opened. ASCII token matching keeps this fixed schema explicit; use a different input policy for identifiers that require other alphabets or numeral systems.

3. Choose what the source stores

Setting	Input/display	Saved value
store: 'raw' (default)	00-012	"00012"
store: 'formatted'	00-012	"00-012"
Optional empty draft	empty	null

Both storage modes preserve string values and leading zeros. required: true rejects clearing. Supply initial source values in the representation you chose; the editor does not make your API imports conform to a mask automatically.

For a dot-separated identifier, use mask: '000.000.000'. Its empty editor shows ___.___.___. Typing 001002003 displays 001.002.003; raw storage keeps the string "001002003". The dots are literal separators, not decimal points, and the mask does not perform numeric arithmetic.

For a fixed North American-style phone layout, use:

const phoneEditor = {
  mask: '+0 (000) 000-0000', store: 'raw',
  label: 'Phone',
};
grid.columns = [{ prop: 'phone', columnType: 'masked', maskedEditor: phoneEditor }];

The raw source string 14155552671 displays +1 (415) 555-2671. This mask enforces a character layout; it does not verify that the phone number exists or support every country’s number length. Select an appropriate country-specific mask or another input flow for international contacts.

4. Customize labels or keep your renderer

Use label and partial validation text to localize the in-cell input and its validation feedback. If your column already owns a renderer, import MaskedEditor from @revolist/revogrid-pro and assign editor: MaskedEditor with the same maskedEditor configuration. ColumnMasked supplies the matching renderer and editor; it does not require DataGridFormattingPlugin.

The mask validates editor drafts. Validate direct source updates, pasted datasets outside this editor, and server imports at their own boundary. See Numeral formats for numeric display masks; they serve a different storage contract.