Cell type model
Understand how one cell type object drives display, editing, clipboard, sort, search, and filter, and which rules keep a custom type safe.
A custom cell type is a bigger decision than a column option. This page explains the model behind the CellType object and the rules that the built-in types follow.
The mental model
A cell type is one object. Cell renders a value, and Editor edits it. The methods toText, fromText, clearValue, and isEmpty form the value pipeline. Clipboard, fill, delete, search, import, and export read through it. Sort uses compare and filter matches the raw value.
The optional members tell the grid more: compare, toDisplayText, toSearchText, align, numeric, validate, activate, href, and filter. The grid reads these members from the type and not from the type name.
One generic implementation of each feature runs against this contract for every type. A bug in fromText therefore reaches every consumer of the type. CellType contract lists each member.
Keypoint checklist
The built-in types follow these rules. Each rule has a reason. CellType contract holds the exact rule for each member.
Value pipeline
Each feature reads a value through its own member. The CellType contract lists the member for print, autosize, clipboard, export, sort, search, filter, and fill. A custom Cell decides its own display.
Search matches text, and filter matches the stored value. A select column searches the choice label. Its filters take the stored choice values and not the labels.
Follow these rules for the methods:
fromTextreceives any text from paste and import. A throw rejects that cell. CallrejectText()for text it cannot parse: the cell keeps its value, and the grid reports the text. ReturnclearValue()only to empty the cell on purpose.- Store serializable primitives. Use an ISO
yyyy-mm-ddstring and not aDate, and a plain number and not a money object. Compare, clipboard, and JSON then stay simple, and no time zone shifts a day. - Choose
isEmptyfor each type. Fortext, the empty string is empty. Fornumberandcheckbox, onlynullandundefinedare empty, so0andfalseare values. For a column with a comparator (compareorsortCompare),isEmptydecides which cells sort last.isEmptyalso decides where Mod+Arrow stops, and which cells Mod+A takes as the data region. - Format for people in
toDisplayText. KeeptoTexta plain string thatfromTextparses back. - Accept a stored value and a displayed label on paste. The
selecttype writes the label intoText, and itsfromTextmatches a pasted value first and a label second.
Rendering and performance
Cell renders once per visible cell, and scrolling mounts cells all the time.
- Create costly objects once. The
datetype keeps itsIntl.DateTimeFormatinstances in a cache. - Key a cache on serialized option values, not on object identity. A column definition creates its
optionsobject on every render, so an identity key never hits. Thedateandnumbercaches key on the locale and the JSON of the format. The JSON is computed once performatobject, so replace the object to change the format. - Pin every locale.
Intlformatters fall back to the runtime locale, and a server and a browser can differ. Thedatetype formats withoptions.localeand defaults toen-US, so server and client text match.
Editor UX
The editor holds its draft. onChange(value) stashes the draft in the grid, and commit(movement?) applies the stashed value and moves the active cell. cancel() discards the edit. Call onChange and then commit, or call commitValue(value, movement) to commit a value in one call. A commit without an earlier onChange applies the opening value.
- Build a text editor on
useCellEditor. It owns the draft, the focus, the one-shot commit guard, and the Enter, Escape, and blur bindings. It ignores Enter and Escape during IME composition. - When an editor commits from more than one path, such as Enter followed by blur, use
useCommitGuard.tryCommit()returnstrueonce, andreset()arms it again. - Commit Enter with
{ dx: 0, dy: 1 }. Commit blur, click-away, and a picked option with{ dx: 0, dy: 0 }. Escape callscancel(), and it never callsonChange. - While
pendingistrue, set the inputreadOnly. Never set itdisabled, because a disabled input cannot receive Escape or blur. WhenrejectionCountchanges, re-arm the commit guard. - Portaled editor content, such as a popover, keeps the edit and the cell range on a press, a double click, and a focus. The
data-grid-cell-editormarker is optional. An editor that commits on blur also commits when the focus moves into its portaled content. - A picker popover, such as
selectordate, commits on an explicit pick. When it closes without a pick, the editor cancels the edit. ThelongTextpopover commits its draft on an outside press and cancels on Escape. - A type with
activatecommits in place. Enter, F2, Space, a click on the active cell, and a double-click callactivate(value, options)and open no editor. Thecheckboxtype uses it. - Leave Tab to the browser. A Tab blur commits with
{ dx: 0, dy: 0 }while the browser moves the focus. A commit with{ dx: 1, dy: 0 }on Tab moves the active cell away from the focus move. - Build editor controls from the
components/uiprimitives of your project.
Typing
Declare the value and options of a custom type through GridCellTypes, so that defineColumns narrows them:
export {};
declare module "@/components/data-grid/types" {
interface GridCellTypes {
currency: {
value: number | null;
options: { currency: string; locale?: string };
};
}
}Set the module path to where components.json installs types.ts. Without the augmentation, a currency column still works, but its options and its value type are unknown.
CellTypeKey is the union of the keys in GridCellTypes. AnyCellType is the value type of a cellTypes registry entry. The data grid entry exports the built-in types as textCellType, numberCellType, checkboxCellType, selectCellType, dateCellType, urlCellType, and longTextCellType.
Wrap the type in defineCellType("currency", currencyCellType). It returns the type unchanged and ties it to the GridCellTypes key.
The cellTypes registry prop does not check an entry against its key. A null entry removes a type. A column whose type matches no entry renders as text, and its edits, pastes, and deletes write nothing. A development warning names the column and the type.