gridcn2.0.0
Editing cells

Editable columns

Choose which cells users can edit, how an edit starts, and which keys commit or cancel it.

A column with accessorKey or setValue is editable until you lock it. The column's cell type supplies the editor, and readOnly locks a column, single cells, or the whole grid. An edit starts only through a deliberate gesture, so a drag to select never opens an editor.

Start an edit

A click selects a cell and never starts an edit. An edit starts in one of three ways:

  • Double-click the cell.
  • Press Enter, F2, or Space on the active cell. The editor opens with the current value.
  • Type a printable character on the active cell. The editor opens with only that character and replaces the old value (type-to-replace).

The edit action owns Enter, F2, and Space, so Space never replaces the value. The typeToReplace action has no key binding. Any unbound printable key triggers it. Set keymap.typeToReplace to move the trigger to other keys, or to [] to turn type-to-replace off. See Shortcut remapping.

Checkbox cells have no editor. A click on the box toggles the value. A click elsewhere in the cell selects it, and a second click toggles it. Enter, F2, and Space toggle the active cell. A drag that starts on a checkbox cell selects a range and toggles nothing.

Commit or cancel an edit

While an editor is open, the editor owns the built-in keys. Built-in grid shortcuts do not run, so Shift+Enter never moves up and Tab keeps its native focus move. A custom command with scope: "editing" or "always" still runs. See Custom commands.

EditorCommitsCancels
text, number, urlEnter or Shift+Enter moves down. Tab or a click away commits without moving the active cellEscape
selectPicking a choice stays in placeEscape, or closing the list without a pick
dateEnter on the typed date moves down. Picking a day stays in placeEscape, or closing the popover
longTextEnter moves down. A click away stays in placeEscape

In a longText editor, Shift+Enter and Alt+Enter insert a line break. A rejected value keeps the editor open. See Validation.

An open edit stays bound to its row id and column id. A sort, a filter, a column reorder, or a row operation that moves the cell moves the editor with it, and the draft survives. If the row or column leaves the view, the grid cancels the edit and discards the draft.

Lock cells

Set readOnly on a column to true, or to a function of the row:

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

type Order = { id: string; email: string; total: number; locked: boolean };

const columns = defineColumns<Order>()([
  { id: "email", header: "Email", accessorKey: "email", readOnly: true },
  {
    id: "total",
    header: "Total",
    accessorKey: "total",
    type: "number",
    readOnly: (row) => row.locked,
  },
]);

export function Orders({ orders }: { orders: Order[] }) {
  return <DataGrid defaultData={orders} columns={columns} />;
}

A locked cell rejects typed edits, paste, fill, and clear. Cells in pinned rows never edit, whatever readOnly says. See Pinned rows. A column that has accessorFn but no accessorKey or setValue locks itself. Add setValue to make a computed value writable. To derive the lock from a user role, see Lock cells by role.

Grid-wide read-only wins

readOnly on <DataGrid> (<DataGridProvider readOnly> in a composed grid) disables every user write in every column, whatever the column says. That covers editing, paste, fill, cut, delete, row operations, undo, and redo. If it turns on during an edit, the grid cancels the edit and discards the draft.

Veto an edit

onBeforeEditStart runs before an editor opens on an editable cell, and before a checkbox toggle. Return false to refuse the edit or the toggle. A returned promise holds the editor until it settles, and a promise that rejects cancels the edit. While the promise is pending, a newer edit start aborts it and runs instead. gateTimeoutMs ends a wait that takes too long: see Cancel async gates.

A checkbox toggle opens no editor, so onEditEnd does not fire for it. Read toggles from onDataChange with source: "edit". Use readOnly to lock a checkbox.

ctx.signal aborts when the active cell moves, the edit is cancelled with Escape, gateTimeoutMs runs out, the grid turns readOnly, or the grid unmounts. This sample refuses the edit of a fixed set of rows:

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

type Task = { id: string; title: string };

const columns = defineColumns<Task>()([
  { id: "title", header: "Title", accessorKey: "title" },
]);
const frozenIds = new Set(["task-1"]);

export function Tasks({ tasks }: { tasks: Task[] }) {
  return (
    <DataGrid
      defaultData={tasks}
      columns={columns}
      onBeforeEditStart={({ rowId }) => !frozenIds.has(rowId)}
    />
  );
}

This sample asks your server and passes ctx.signal to the request. A request that the signal aborts rejects, and the edit does not start:

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

type Task = { id: string; title: string };

const columns = defineColumns<Task>()([
  { id: "title", header: "Title", accessorKey: "title" },
]);

export function LockedTasks({ tasks }: { tasks: Task[] }) {
  return (
    <DataGrid
      defaultData={tasks}
      columns={columns}
      onBeforeEditStart={async ({ rowId }, { signal }) => {
        const response = await fetch(`/api/tasks/${rowId}/lock`, { signal });
        const { locked } = (await response.json()) as { locked: boolean };
        return !locked;
      }}
    />
  );
}

When an edit ends, onEditEnd reports commit or cancel. For each refused commit, it reports rejected, and the editor stays open. See Edit and validation events.

Server mode

An edit reaches onDataChange and onSave with source: "edit". readOnly and onBeforeEditStart run in the browser only, so enforce the same rule on your server. Save edits shows how to send the change.

Props

PropTypeDefault
typestring"text"
optionsunknownnone
readOnlyboolean | ((row) => boolean)none
accessorFn(row) => valuenone
setValue(row, value) => rownone
PropTypeDefault
readOnlybooleanfalse
onBeforeEditStart(cell, ctx: { signal: AbortSignal }) => boolean | void | Promise<boolean | void>none
onEditEnd(event) => voidnone
keymapKeymapnone

Column definition and DataGrid props list every prop.

On this page