Plugin model
Learn how plugins combine in one grid, the order they run in, what they reach, and when the grid resolves them again.
A plugin is a plain object that reaches into the grid. The plugins prop of DataGridProvider takes an array of plugins. Many first-party add-ons install one plugin: fill, find and replace, history, the keyboard shortcuts dialog, pinned rows, presence, and server rows. Your own code passes its plugins through the same prop.
The plugin shape
A plugin needs only name. Every other member is optional, and a plugin holds the members it needs:
nameis the identity of the plugin and the React key of its components. Keep it unique per grid. When two plugins share a name, the grid ignores the later one and logs a development warning.Overlayis a component that paints into the overlay layer. See Plugin overlays.rowBandsadds rows to the top band, the bottom band, or both. See Plugin overlays.onDataChangeobserves every data change. See Plugin events.commandsadds named commands to the grid. See Plugin commands and shortcuts.keymapbinds keys to the commands of the plugin. A core action takes its keys from yourkeymapprop. The add-on actions take theirs from the plugin of the add-on.Mountis a component that runs engine work inside the grid.cellMenuItemsreturns items for the cell menu, in plugin order.
The array order is the precedence order. Overlays paint in array order, bands stack in array order, and observers run in array order. The first plugin keeps a command name. Your commands prop wins over every plugin, with no warning. For keys the earlier plugin wins: a later plugin that binds a taken key loses that binding, with a development warning.
This plugin logs the source of every data change:
"use client";
import { useMemo } from "react";
import {
DataGridBody,
DataGridHeader,
DataGridProvider,
DataGridRoot,
defineColumns,
type DataGridPlugin,
} from "@/components/data-grid/data-grid";
type Person = { id: string; name: string };
const columns = defineColumns<Person>()([
{ id: "name", header: "Name", accessorKey: "name" },
]);
function useChangeLogger(): { plugin: DataGridPlugin } {
return useMemo(
() => ({
plugin: {
name: "change-logger",
onDataChange: (_next, change) => console.log(change.source),
},
}),
[],
);
}
export function PeopleGrid({ rows }: { rows: Person[] }) {
const { plugin } = useChangeLogger();
return (
<DataGridProvider
defaultData={rows}
columns={columns}
getRowId={(row) => row.id}
plugins={[plugin]}
>
<DataGridRoot className="h-96">
<DataGridHeader />
<DataGridBody />
</DataGridRoot>
</DataGridProvider>
);
}Engine work
Mount is a component that DataGridRoot renders after its children. It takes no props. It reads the grid through useDataGridApi.
Keep an Overlay paint-only. When a plugin needs pointer work, listeners, or timers, run them in Mount. The fill add-on runs its drag engine from Mount and paints the preview from Overlay.
What a plugin can reach
An observer and a command receive api, the imperative handle of the grid. It reads every state value and writes only through actions:
api.storeis a read-only view of the store. It hasgetState(),getInitialState(), andsubscribe(). It has nosetState.api.store.getState()returns the live state objects. Its type,DataGridReadState, leaves out the internal slots and moston*callbacks of your props. Do not read or call the left-out values.onSave,onSaveRejected,onBeforeDeleteRows,onRowActionSkipped,onGateAborted,onPageChange, andonPageSizeChangestay in the state. Never mutate the state objects.api.actionsholds the public actions. A plugin writes data only through them.
A plugin that needs a value the context does not carry subscribes to the store with api.store.subscribe((state, prev) => ...).
Identity
The grid compares your plugins array entry by entry. When two arrays have the same length, the same name at each position, and identical members, they are equal. Equal arrays re-resolve nothing. The store keeps its resolved plugin list, merged commands, and merged keymap.
An inline plugins={[plugin]} array is safe while each plugin object keeps its identity. The plugin that a first-party hook returns keeps its identity.
Two changes force a re-resolution:
- A plugin with the same
nameand a changed member, such as a rebuiltOverlaycomponent or a newonDataChangeclosure. React remounts a component whose type changed, and a development warning names it. - A different array shape: a plugin added, removed, or moved.
A plugin object attaches to one grid. When you pass it to a second grid, the second grid drops it, keeps the rest of its list, and logs a development warning.
Server rendering
The grid renders row bands during server rendering, and the server markup carries the band heights. Write a plugin component so that it renders the same text on the server and on the client. Pin any locale-dependent formatting, and read no browser-only global, such as window, while it renders.