gridcn2.0.0
Events and state

Edit and validation events

Stop an edit before it opens, learn how an edit ended, and read the cells that a bulk write refused.

Three callbacks cover the edit lifecycle. onBeforeEditStart runs before an editor opens. onEditEnd reports how a session ended. onValidationError reports the cells that a paste, a fill, a delete, a cut, or a batch update refused.

PropFires whenDefault
onBeforeEditStartAn editor is about to opennone
onEditEndA session ends, or validation refuses a commit attemptnone
onValidationErrorA bulk write settles with at least one refused cellnone

onBeforeEditStart

The callback fires right before an editor opens. Enter, F2, Space, type-to-replace, and a double-click open an editor. The payload is a ViewCellRef: rowId, columnId, viewRowIndex, and viewColumnIndex. Return false to stop the edit. The grid then makes no state change. This sample stops the edit of a locked row:

import { DataGrid, defineColumns } from "@/components/data-grid/data-grid";

type Row = { id: string; name: string };

const columns = defineColumns<Row>()([
  { id: "name", header: "Name", accessorKey: "name" },
]);

const lockedIds = new Set(["r1"]);

function Grid({ rows }: { rows: Row[] }) {
  return (
    <DataGrid
      defaultData={rows}
      columns={columns}
      onBeforeEditStart={({ rowId }) =>
        lockedIds.has(rowId) ? false : undefined
      }
    />
  );
}

The second argument is a GateContext. Its signal aborts when the active cell moves to another cell, the edit is cancelled, the grid becomes readOnly, or the grid unmounts.

The callback also fires for the startEditing action. It does not fire on a readOnly grid. It does not fire for a cell that its column makes read-only for that row. For a cell whose type declares activate, such as a checkbox, it fires before the toggle. false or a pending promise holds the toggle.

Return a promise to decide later. The editor opens after the promise settles. Three cases open no editor: the promise resolves to false, the user moved to another cell, or the grid became readOnly. A newer edit start aborts the pending one. A rejection cancels the edit start.

onEditEnd

The payload is a ViewCellRef plus result. The committed value is not in the payload. onDataChange carries it.

resultMeaning
commitThe session closed and the grid wrote the value, or the value equaled the old value
cancelThe grid discarded the draft
rejectedValidation refused a commit and the session stays open

Each session ends with exactly one commit or cancel. rejected fires once per refused attempt, so a session can report it many times before it ends.

These causes end a session with cancel:

  • The user presses Escape.
  • actions.cancelEditing() or the cancel() of an editor discards the draft.
  • A second startEditing replaces the open session.
  • A filter, a hidden column, or a data change removes the edited cell from the view.
  • The grid becomes readOnly.

A sort that only moves the edited row fires nothing.

If the edited cell leaves the view, the grid also clears the active cell. Other rows can stay in the view.

A commit that moves the active cell fires onActiveCellChange and onSelectionChange, then onDataChange, then onEditEnd. With an async Standard Schema, the editor stays open, and its pending prop is true until the schema settles (Editor).

The callback runs after the grid writes the change. If it throws, the commit or the cancel stays, and the grid rethrows the error after the other callbacks ran. When a view change ends the edit, a throw goes to the console as [data-grid] onEditEnd threw: instead. See Callback timing and errors.

onValidationError

The callback fires after a paste, a fill, a delete, a cut, an updateCells call, or a toggle of an activate cell settles. If validation refused no cell, it does not fire. The grid applies the accepted cells first, so their onDataChange fires before this event.

The payload is { source, rejected }. source is "paste", "fill", "stream", "replace", "delete", "cut", or "edit". updateCells and updateRows report the source of the call. A find and replace batch reports "replace". The Delete key reports "delete", and Cut reports "cut". A validator that refuses the toggle of an activate cell, such as a checkbox, reports "edit". Each entry of rejected has these fields:

FieldMeaning
rowIdThe row id of the refused cell
columnIdThe column id of the refused cell
viewRowIndexThe view index of the row, or -1 for a row outside the view
valueThe value that failed
messageThe message of the validator

A single cell edit does not use this event. onEditEnd with result: "rejected" covers that case.

Soft columns

A column with validationMode: "warn" commits a refused value from an edit, closes the editor, and flags the cell. Paste, fill, updateCells, and import commit the refused cells of such a column too and flag them. They call onValidationError for no flagged cell.

On this page