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.
| Editor | Commits | Cancels |
|---|---|---|
text, number, url | Enter or Shift+Enter moves down. Tab or a click away commits without moving the active cell | Escape |
select | Picking a choice stays in place | Escape, or closing the list without a pick |
date | Enter on the typed date moves down. Picking a day stays in place | Escape, or closing the popover |
longText | Enter moves down. A click away stays in place | Escape |
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
| Prop | Type | Default |
|---|---|---|
type | string | "text" |
options | unknown | none |
readOnly | boolean | ((row) => boolean) | none |
accessorFn | (row) => value | none |
setValue | (row, value) => row | none |
| Prop | Type | Default |
|---|---|---|
readOnly | boolean | false |
onBeforeEditStart | (cell, ctx: { signal: AbortSignal }) => boolean | void | Promise<boolean | void> | none |
onEditEnd | (event) => void | none |
keymap | Keymap | none |
Column definition and DataGrid props list every prop.
Related
- Built-in cell types: the editor each type opens.
- Validation: reject a value before it commits.
- Cell type model: how a type turns text into a value.
- Column definition: every column prop.
- Shortcut remapping: move the edit keys.