Plugin API
Look up the members of DataGridPlugin, the context types they receive, and the rules for names, order, conflicts, and global shortcut flags.
A plugin is a plain object of type DataGridPlugin<TData>. The plugins prop of DataGridProvider and DataGrid takes a readonly DataGridPlugin[]. Import the plugin types from @/components/data-grid/data-grid.
| Member | Type | Role |
|---|---|---|
name | string | The identity of the plugin and the React key of its components. |
Overlay | ComponentType<OverlayPluginCtx> | Paints into the overlay layer. |
rowBands | PluginRowBands | Adds rows to the top band, the bottom band, or both. |
onDataChange | (next, change, ctx) => void | Observes every data change. |
commands | Record<string, GridCommand<TData>> | Adds named commands. |
keymap | Keymap | Binds keys to the commands of the plugin. |
Mount | ComponentType | Runs engine work inside DataGridRoot. |
cellMenuItems | (ctx) => PluginMenuItem[] | Adds items to the cell menu. |
A plugin needs only name. Plugin model explains the model, and Write a plugin builds one.
Members
name
name must be unique per grid. When two plugins share a name, the grid ignores the later one and warns in development.
Overlay
Overlay is a component. The grid renders it with the values of OverlayPluginCtx as props, after the range layers and before the active-cell ring. See Plugin overlays.
rowBands
rowBands is a PluginRowBands object:
| Member | Type | Meaning |
|---|---|---|
top | readonly unknown[] | The rows above the first data row. Omit it for no top band. |
bottom | readonly unknown[] | The rows below the last data row. Omit it for no bottom band. |
render | (ctx: RowBandRenderCtx) => ReactNode | Paints the rows of one band. The root calls it as a plain function while it renders. |
onDataChange
The grid calls onDataChange(next, change, ctx) after the store write, your onDataChange prop, and your onSave prop. Observers run in array order. An observer that throws logs a console warning, and the remaining observers still run. See Plugin events.
commands
commands maps a command name to a GridCommand. The grid drops a command that has the name of a built-in action. See Plugin commands and shortcuts.
keymap
keymap binds keys to commands of the same plugin. A command name needs no entry in GridActions. The grid drops an entry that names a core action, or a command that the plugin does not define. The entry is the full binding list of its action and replaces its bindings, like the same entry in your keymap prop.
The grid drops a key that another action already holds. Your keymap prop keeps its keys. Among plugins, the earlier plugin keeps a key. One exception applies when your keymap leaves out focusSearch. Then a plugin binding takes the default focusSearch key, and a development warning names the plugin. The find and replace add-on takes it with no warning. See Plugin commands and shortcuts.
Mount
Mount is a component without props. DataGridRoot renders it after its children. Read the grid through useDataGridApi.
cellMenuItems
cellMenuItems receives the right-clicked row id, view row index, column id, the target row ids, and the grid actions. The cell menu of DataGridContextMenu appends the returned items after the built-in items, behind a separator, in plugin order. The getCellMenuItems resolver then sees the whole set. A function that throws adds no items.
Context types
| Type | Members |
|---|---|
DataGridPluginCtx<TData> | api: the DataGridApi of the grid that the change belongs to. |
RowBandRenderCtx | position, rows, rowOffset, renderedColumns, layout, rowHeight, template, headerHeight, ariaRowIndexBase. |
OverlayPluginCtx | windowStart, clampRowStart, clampRowEnd, colCount, colOffset, pinTrack, selectionPointer, columnIndexOf, splitRectByPinZones, clampRectToWindow. |
Plugin overlays explains each value of RowBandRenderCtx and OverlayPluginCtx.
Resolution rules
| Situation | Result |
|---|---|
Two plugins share a name | The grid keeps the first and ignores the later one. |
| The same plugin object sits in a second grid | The second grid drops it, keeps the rest of its list, and warns in development. |
The array has the same length, the same name per entry, and identical members | The grid resolves nothing again. |
An Overlay or Mount gets a new identity under the same name | The component remounts and loses its state. Development mode warns. |
| Several plugins add to one band | The root renders one segment per plugin, in array order. |
Global shortcut flags
DataGridGlobalShortcuts enables an action through a boolean flag of the same name. undo and redo default to true. Every other flag defaults to false. The flags form GlobalShortcutsConfig, the type DataGridGlobalShortcutsProps. GlobalShortcutAction is GridAction. A plugin that backs a GridAction offers its flag by augmenting DataGridGlobalShortcutActions. The history add-on does this for undo and redo, and the fill add-on for fillDown and fillRight.
Two rules apply to an added action. Every binding of the action starts with mod. The action makes sense without grid focus, because the flag takes its key from the browser on the whole page. For example, a flag on openFind takes Mod+F from the whole page.
Declare the action in GridActions too. This sample adds a custom action exportCsv and its flag. Put it in a file that has an import or an export:
export {};
declare module "@/components/data-grid/types" {
interface GridActions {
exportCsv: true;
}
}
declare module "@/components/data-grid/keyboard/global-shortcuts" {
interface DataGridGlobalShortcutActions {
exportCsv: boolean;
}
}Global shortcuts lists the flags that the core offers.