Pick a code route
Step 1 of 3
Choose the lightest way to change the grid with your own code, from a column option to a custom cell type or a plugin.
Before you start, render your first grid with columns and defaultData. This step is the first of the custom code path. It ends with one choice: the route that fits your change.
Take the first row that fits. A lighter route leaves less code for you to keep.
Choose a route
| If you need to | Route | Guide |
|---|---|---|
| Format numbers, dates, or link text | The type and options of a column | Built-in cell types |
| Draw other content in a cell and keep the editor, the sort, and the copy | renderCell on the column | Display override |
| Store a new kind of value, or edit it in a new way | A custom cell type in cellTypes | Plan a cell type |
| React to every change in your app | The onDataChange prop of the grid | Data change events |
| Paint over the grid, add rows above or below the data, observe every change in a reusable object, or add a command | A plugin in plugins | Plan a plugin |
| Call a grid operation from your own button or panel | The actions of the grid | Run bulk actions |
When a cell is in edit mode, the editor of its cell type replaces the content that renderCell draws. A row that has not loaded yet shows a skeleton, and renderCell does not run for it.
See the hook-in points
Each route attaches at one place. This grid uses renderCell, a plugin, and the actions:
"use client";
import { useRef, useState } from "react";
import {
DataGrid,
defineColumns,
type DataGridApi,
type DataGridPlugin,
} from "@/components/data-grid/data-grid";
type Player = { id: string; name: string; score: number | null };
const columns = defineColumns<Player>()([
{ id: "name", header: "Name", accessorKey: "name" },
{
id: "score",
header: "Score",
accessorKey: "score",
type: "number",
renderCell: ({ value }) => <progress max={100} value={value ?? 0} />,
},
]);
function createAuditPlugin(): DataGridPlugin {
return {
name: "audit",
onDataChange: (_next, change) => console.log(change.source),
};
}
function resetFirstScore(grid: DataGridApi<Player> | null, players: Player[]) {
const first = players[0];
if (!first) return;
grid?.actions.updateCells(
[{ rowId: first.id, columnId: "score", value: 0 }],
{ source: "edit" },
);
}
export function Players({ players }: { players: Player[] }) {
const gridRef = useRef<DataGridApi<Player>>(null);
const [plugin] = useState(createAuditPlugin);
return (
<>
<button onClick={() => resetFirstScore(gridRef.current, players)}>
Reset the first score
</button>
<DataGrid
ref={gridRef}
defaultData={players}
columns={columns}
plugins={[plugin]}
aria-label="Players"
className="h-96"
/>
</>
);
}The button passes { source: "edit" }. Without source, the write is a push: it has no undo and never reaches onSave. A custom cell type attaches through the cellTypes prop in the same way. A plugin object attaches to one grid, so create one object for each grid. Plan a plugin writes createAuditPlugin in its own file.
Result
You know which route fits your change.
Next: Plan a cell type, or skip to Plan a plugin. If your route is a column option, renderCell, or the actions, follow its guide in the table and skip to the task finder.
Related
Go live with streaming
Push live values from a WebSocket into the grid by row id with updateCells, without a refetch and without sending the push back to your server.
Plan a cell type
Decide the stored value, the text form, the empty value, and the editor of a custom cell type, then write the type as one typed object.