Editing & cell types

Edit activation

A single click never starts editing. It only moves the active cell. Editing starts only through one of these actions:

• Double-click a cell.
• Press Enter, F2, or Space on the active cell. This opens the editor seeded with the current value. Space is not a printable character, so it never type-to-replaces.
• Type a printable character on the active cell. This is type-to-replace: the editor opens seeded with only what you typed, and replaces the old value.

This removes any ambiguity between a plain drag-to-select gesture and the start of an edit.

To commit a value, the built-in editors follow one keyboard contract. While an editor is open, the grid's keymap is ignored and the editor owns every key, so the keymap's commitUp (Shift+Enter) binding never fires during an edit, and Tab / Shift+Tab keep their native focus move. The actual per-editor behavior:

The table means this:

• Any Enter moves down, never up.
• Tab never moves the active cell. It commits and lets the browser move focus.
• A popover editor without an explicit pick cancels rather than commits.

An open edit stays bound to its row when the view changes. A re-sort, a filter, a column reorder, or a row insert, delete, duplicate, or reorder that moves the edited row moves the editor with it, and the typed draft survives. When the row or column leaves the view, the edit is cancelled and the typed value is discarded. It is never written into a row that is no longer visible.

Built-in cell types

Every cell type implements the same small pipeline (display = toDisplayText ?? toText, clipboard/export = toText, sort = compare, fill = raw value) so one override changes how a type converts text to and from a value. The full per-feature contract, including how search and filter match values, is on custom cell types.

const columns = defineColumns<Person>()([
  { id: "name", header: "Name", accessorKey: "name", type: "text" },
  { id: "age", header: "Age", accessorKey: "age", type: "number", options: { min: 0, max: 120 } },
  { id: "active", header: "Active", accessorKey: "active", type: "checkbox" },
  {
    id: "role",
    header: "Role",
    accessorKey: "role",
    type: "select",
    options: { choices: [{ value: "admin", label: "Admin" }, { value: "user", label: "User" }] },
  },
  { id: "joined", header: "Joined", accessorKey: "joined", type: "date" },
] as const);

Date specifics

The value and clipboard representation are always ISO yyyy-mm-dd, regardless of display. Formatting is for presentation only, and never affects what the grid copies, pastes, or stores. options.displayFormat (an Intl.DateTimeFormatOptions object) and options.locale control toDisplayText. The editor is a popover date-picker built from shadcn's calendar and popover, with typed-input passthrough. The popover opens at the cell's start edge, and the cell text stays in place. Enter commits the value, and Escape cancels it.

{
  id: "joined",
  header: "Joined",
  accessorKey: "joined",
  type: "date",
  options: { displayFormat: { year: "numeric", month: "short", day: "numeric" }, locale: "en-US" },
}

options.calendarTrigger New shows the editor as a typed input with a calendar button. The calendar stays closed until the button opens it, and the button toggles it. The button reads its label from labels.grid.dateCalendarAriaLabel. Without the option, the calendar shows when the edit starts.

Number formatting

options.format (an Intl.NumberFormatOptions object) and options.locale (default "en-US") render the value with locale formatting: currency, percent, compact. Formatting is display only. toText, the editor, copy, paste, sort, and export keep the raw number, so a stored 0.25 under style: "percent" displays as 25% and edits as 0.25. When decimals is set and the format declares no fraction digits, decimals sets both the minimum and the maximum fraction digits. Invalid format options (for example style: "currency" without a currency) fall back to the raw value and log a one-time dev warning.

{
  id: "price",
  header: "Price",
  accessorKey: "price",
  type: "number",
  options: { format: { style: "currency", currency: "USD" } },
}

URL links

The value is a URL. The cell renders a safe link that opens in a new tab without a referrer and is not a tab stop. A plain click on the link selects the cell only. Ctrl+click (Cmd+click on macOS) and middle-click open the link in a new tab. alt+Enter (openLink) opens the link of the active cell. Only values with an http, https, or mailto protocol render as a link; every other value renders as plain text. options.label maps the stored URL to the shown link text. toText and copy stay the URL.

Long text

longText stores multi-line text verbatim. The cell is one line and shows the first 500 characters with line breaks as spaces. The editor is a popover with a multi-line textarea. The popover opens over the cell, with its top-left corner on the cell's corner and its first line on the cell text: Enter commits and moves down, Shift+Enter and Alt+Enter insert a line break, Escape cancels, and an outside press commits the draft. options.maxLength (default 100,000) caps the stored text: the editor's textarea enforces it while typing, and a type-level validate rejects pasted, filled, or imported text longer than the default. A column with a custom maxLength declares its own validate to get the same rejection message on those paths.

Read-only

Per-column, static or row-dependent:

{ id: "email", header: "Email", accessorKey: "email", type: "text", readOnly: true }
// or
{ id: "email", header: "Email", accessorKey: "email", type: "text", readOnly: (row) => row.locked }

Validation

See the live examples: Validation · Async validation · Server errors · Cross-field

validate accepts either of two forms:

• A function that returns an error message to reject a value, or null to accept it. The function is your code, so side effects work. The demo's Age rule fires a toast from inside it.
• Any Standard Schema for the value of the column: Zod, Joi, Valibot, Yup, ArkType, or any other library that implements the spec. gridcn detects the schema structurally ("~standard" in validate), so no adapter is necessary for a conforming library.

A cell type can declare the same validate as a default for its columns, and a column's own validate wins over the type's. Every validation path (a single-cell commit, a paste, a fill, updateCells, and import) resolves column.validate ?? cellType.validate. See custom cell types.

If a validator throws, or its promise rejects, the grid rejects the value and shows the error message. This applies to every validation path, and a throwing validator blocks the edit on an onInvalid: "warn" column too.

// Function form
{
  id: "age",
  header: "Age",
  accessorKey: "age",
  type: "number",
  validate: (value) => (typeof value === "number" && value < 18 ? "Must be 18 or older" : null),
}

// Standard Schema form — illustrative, schema-agnostic (works with Zod, Joi, Valibot, ...)
{
  id: "age",
  header: "Age",
  accessorKey: "age",
  type: "number",
  validate: z.number().min(18, "Must be 18 or older"),
}

Soft rules: onInvalid

By default a rejection is blocking: the value never commits. onInvalid: "warn" commits the value and flags the cell instead: the same ring, tint, and hover tooltip as a server error, auto-cleared by the next valid commit of that cell. The editor closes, because from the grid's point of view the commit succeeded:

{
  id: "notes",
  header: "Notes",
  accessorKey: "notes",
  validate: (value) => (typeof value === "string" && value.length > 12 ? "Max 12 characters" : null),
  onInvalid: "warn",
}

"warn" works with every validate form: function and sync/async Standard Schema. A rejection carries no transformed value, so a soft commit stores the raw input. Per-row softness is the function form's row argument (return null to skip the rule for that row). Bulk paths (paste, fill, updateCells) still drop rejected cells, even in soft columns.

Transforms are committed

A schema can transform the value, for example to trim, coerce, or round it. On success, the grid commits the schema's OUTPUT (result.value), not the raw input. So a transforming schema changes what data your grid stores, not only what value it allows:

validate: z.coerce.number().int() // "42.9" committed as 42, not "42.9"

Async schemas

The validate function of a Standard Schema can return a Promise, for an async uniqueness check for example. The same column definition then applies to a single edit and to every bulk path:

{
  id: "sku",
  header: "SKU",
  accessorKey: "sku",
  validate: z.string().refine(async (sku) => await isSkuFree(sku), "Already in use"),
}

On a single-cell edit, when you type a value and press Enter or Tab, or move away:

• The editor stays open while the schema resolves. The built-in text and number editors mark their input readOnly, as the pending treatment. They never mark it disabled, so Escape still cancels. See Build your own cell type for the same pending and rejectionCount contract in a custom editor.
• If the schema resolves with issues, the rejection message appears exactly like a sync rejection, and editing continues.
• If the schema resolves successfully, the committed value is the schema's result.value. The grid then applies the pending cell-to-cell movement, the delta from Enter.
• Escape, the start of a newer commit, or the unmount of the cell invalidates an in-flight validation. Its resolution is dropped silently, and never applied late.

On bulk paths

Paste, fill, CSV/XLSX import, and updateCells hold the batch while the schema resolves:

• The grid validates a maximum of 32 cells at the same time. A paste of 10,000 cells therefore makes 32 concurrent calls, not 10,000.
• Nothing changes until every verdict is in. The accepted cells then commit together, as one onDataChange with one operations batch, the same as a sync bulk write. An import above 5,000 rows validates in chunks internally, and still hands the whole row array to onImport at once.
• A rejected cell drops, and the other cells of the batch still commit. One bad value never fails the batch. Paste, fill, and updateCells report the rejected cells through onValidationError when you pass one. updateCells also reports them in its return value, and import reports its rejected cells through its return value.
• The committed value is the schema's result.value, so a transform applies on bulk paths too.
• A newer operation supersedes a held batch: a second paste over the same area, a data change, a sort or filter change, or the unmount of the grid drops the older batch silently.
• The import dialog keeps its Import button disabled while it validates. Cancel, or closing the dialog, aborts the build and drops the batch.

Cross-field rules: validateRow

<DataGrid
  {...grid}
  validateRow={(row) => (row.discount > row.price ? { discount: "Discount above price" } : null)}
/>

validateRow runs once per touched row after a write gesture commits (a single edit, a paste, a fill, or a bulk update) against the row with ALL of the gesture's cells applied, so the verdict never depends on column order (a per-column validate runs mid-gesture and cannot guarantee that).

Return columnId -> message to mark cells, or null when the row is fine. Messages land in the same per-cell error display as Server errors (ring, tint, hover tooltip, aria-invalid), and the values still commit (the same stance as server errors, no rollback). A later write that makes the row consistent clears the verdict, even when it writes a different column than the marked one.

validateRow does not run on row insert or duplicate (a fresh default row is expected to be incomplete), on row deletion, or on a data array you replace yourself. It must be synchronous.

Server errors

validate runs before commit. A server can still reject an already-committed value later, for example with a 422 response that names the field. actions.setCellErrors paints that rejection on the cell, in the same round trip as onDataChange. Hovering the marked cell shows the message in a tooltip:

The rejection lands a round trip after onDataChange, long after the grid is mounted, so the handler reaches the grid's actions through the imperative handle (no lifted store needed):

function OrdersGrid() {
  const [data, setData] = useState<readonly Order[]>(initialOrders);
  const gridRef = useRef<DataGridApi<Order> | null>(null);

  function handleDataChange(next: readonly Order[], change: DataChange<Order>) {
    setData(next);
    saveOrders(change.ops).catch((error) => {
      gridRef.current?.actions.setCellErrors(parseFieldErrors(error)); // [{ rowId, columnId, message }]
    });
  }

  return (
    <DataGrid ref={gridRef} data={data} columns={columns} getRowId={(row) => row.id} onDataChange={handleDataChange} />
  );
}

The cell gets the same ring, tint, and aria-invalid treatment as a rejected validate call. Open the cell for editing, and the message shows the same way a live rejection does.

The moment the user commits a new value to that cell, through any write path (a single edit, paste, fill, updateCells, or a cleared selection), the error clears on its own. The server can set it again if the new value is still wrong.

type CellErrorEntry = { rowId: string; columnId: string; message: string };

actions.setCellErrors(errors: readonly CellErrorEntry[]): void; // merges in, per cell
actions.clearCellErrors(targets?: readonly { rowId: string; columnId: string }[]): void; // omit targets to clear every cell

useDataGridCellErrors() reads the full map (ReadonlyMap<string, string>) for a summary view, for example an error count badge. Build a lookup key with the exported cellErrorKey:

import { cellErrorKey, useDataGridCellErrors } from "@/components/data-grid/data-grid";

const errors = useDataGridCellErrors();
const message = errors.get(cellErrorKey(row.id, "email"));

Display override without a new type

renderCell swaps only the display, and keeps the type pipeline of the column unchanged: edit, sort, clipboard, and paste.

{
  id: "score",
  header: "Score",
  accessorKey: "score",
  type: "number",
  renderCell: ({ value }) => <ProgressBar value={value} />,
}

Custom cell types

A cell type is { Cell, Editor, toText, fromText, clearValue, isEmpty, compare?, align? }. Register custom types through the cellTypes prop on DataGridProvider. To get the same options and value inference through defineColumns that built-in types get, augment GridCellTypes through declaration merging and wrap the type in defineCellType.

The cellTypes prop merges over the built-ins: built-ins you do not name keep working, a key that names a built-in replaces that built-in, and a key set to null removes that type. Columns that use a removed or unknown type fall back to the built-in text type. See Build your own cell type.

See Build your own cell type for the full contract walk-through. It has a keypoint checklist distilled from lessons learned from the built-in types, on performance caching, SSR-safe formatting, editor commit semantics, and popover outside-click handling, plus a complete worked currency example. Recipes has a shorter minimal version, and API reference has the exact contract types.