Write a plugin
Write a plugin that paints a tinted band over one column and follows scroll, resize, and pinned columns.
Write a plugin to paint on the grid, observe data changes, or add a command. This task builds a plugin that tints one column. A plugin object holds the parts it needs, and name is the only required part.
Coordinates
A view index is a row position in the sorted and filtered order. A rect is { x, y, width, height }: x is a visible column index and y is a view index. A pin zone is the start side, the unpinned middle, or the end side of the grid.
Plugin parts
A plugin object attaches to one grid, so create one object per grid. A plugin with a name that another plugin of the grid holds is ignored, with a development warning. Pick the part you need:
Overlaypaints.rowBandsadds rows.onDataChangeobserves writes.commandsadds commands, andkeymapbinds keys to them. A key that another action holds stays with that action.
The grid renders Mount inside the grid root.
Steps
- Write a component that takes the overlay
ctxand returns the band. The grid renders it after the selection fills and before the active-cell ring. - Return
OverlayRectwith thectxand a rect. It clamps the rect to the rendered rows, splits it at pinned columns, and places each part on the grid lines. Style it withclassName. - Read the column from React context and not from a closure. A new
Overlayfunction remounts the overlay and logs a warning in development. - Return
{ name, Overlay }from a factory and pass the result inplugins.
Paint a column
The sample below does all four steps. ./orders stands for your own module of columns and orders rows. Create the plugin once per grid with useState:
"use client";
import { createContext, useContext, useState } from "react";
import {
DataGrid,
type DataGridPlugin,
type OverlayPluginCtx,
} from "@/components/data-grid/data-grid";
import { OverlayRect } from "@/components/data-grid/data-grid-sdk";
import { columns, orders } from "./orders";
const HighlightedColumn = createContext<number | null>(null);
function ColumnOverlay(ctx: OverlayPluginCtx) {
const column = useContext(HighlightedColumn);
if (column === null) return null;
const rect = {
x: column,
y: ctx.clampRowStart,
width: 1,
height: ctx.clampRowEnd - ctx.clampRowStart,
};
return <OverlayRect ctx={ctx} rect={rect} className="bg-primary/10" />;
}
function createColumnHighlight(): DataGridPlugin {
return { name: "column-highlight", Overlay: ColumnOverlay };
}
export function OrdersGrid() {
const [column, setColumn] = useState<number | null>(null);
const [plugin] = useState(createColumnHighlight);
return (
<HighlightedColumn.Provider value={column}>
<button onClick={() => setColumn(1)}>Highlight the second column</button>
<DataGrid
className="h-96"
defaultData={orders}
columns={columns}
plugins={[plugin]}
/>
</HighlightedColumn.Provider>
);
}Result
A click on the button tints the second column across the rendered rows. The band lives in the scrolling canvas, so it moves with the cells. It splits at pinned columns. The active-cell ring stays above it.
An inline plugins={[plugin]} array is safe while the plugin object keeps its identity. A new object with the same name and a changed member makes the grid resolve the plugins again.
Related
- Plugin overlays: every
ctxfield and the coordinate rules. - Plugin model: the parts of a plugin object and what they do.
- Plugin events: observe data changes from a plugin.
- Plan a plugin: choose the parts before you write one.