Plan a plugin
Step 3 of 3
Choose the parts of a plugin, give it a name and one owner grid, and write the first plugin as a factory that observes data changes.
Before you start, pick a code route and choose a plugin. A plugin is a plain object in the plugins prop. It changes the grid without a change to the grid source. This step picks its parts and writes a first plugin.
Choose the parts
A plugin needs only a name. Add the parts that your change needs:
| If you need to | Add |
|---|---|
| Paint over the cells | Overlay |
| Add rows above or below the data | rowBands |
| Observe every data change | onDataChange |
| Add a command and its keys | commands, and keymap to bind the keys to those commands |
| Back undo, redo, fill, or find with your own command | commands under the action name, such as undo, and keymap with its keys, such as { undo: ["mod+z"] }. The core binds no key to an add-on action. |
| Run pointer work, listeners, or timers inside the grid root | Mount |
Keep an Overlay paint-only. Put pointer work, listeners, and timers in Mount. A Mount component takes no props and reads the grid through useDataGridApi.
Fix the rules before you write
- Give the plugin a
namethat no other plugin of the grid uses. The grid ignores a second plugin with the same name, and development mode warns. - Create one plugin object for each grid. A second grid drops an object that another grid holds, and warns in development.
- Keep the identity of the object. Create it once with
useStateoruseMemo. AnOverlayorMountcomponent that changes identity remounts. - Order the array on purpose. The array order is the paint order and the observer order. The first plugin keeps a command name and a key that a later one also takes.
Write the first plugin
An observer receives every change. That includes the revert of a refused save and a server push. This factory reports the row ids of user edits only:
import type { DataGridPlugin } from "@/components/data-grid/data-grid";
export function createAuditPlugin(): DataGridPlugin {
return {
name: "audit",
onDataChange: (_next, change) => {
if (change.source !== "edit") return;
console.log(change.ops.map((op) => op.rowId));
},
};
}Pass the result in plugins, once for each grid:
"use client";
import { useState } from "react";
import { DataGrid, defineColumns } from "@/components/data-grid/data-grid";
import { createAuditPlugin } from "./audit-plugin";
type Person = { id: string; name: string };
const columns = defineColumns<Person>()([
{ id: "name", header: "Name", accessorKey: "name" },
]);
export function PeopleGrid({ rows }: { rows: Person[] }) {
const [plugin] = useState(createAuditPlugin);
return (
<DataGrid
defaultData={rows}
columns={columns}
plugins={[plugin]}
aria-label="People"
className="h-96"
/>
);
}An observer reads the grid through ctx.api, its third argument. api.store offers getState and subscribe and no setState. Write through api.actions.
Result
The console lists the row ids after each cell edit. A paste, a fill, an undo, a revert, and a server push log nothing, because each has another source.
Where next: Write a plugin for an overlay that follows scroll and pinned columns, the Plugin API, or the task finder.