Plugin overlays
Learn how a plugin paints into the overlay layer and the row bands, which context values it receives, and which coordinates it uses.
A plugin paints in two places. The Overlay member paints above the cells, inside the scrolling canvas. The rowBands member adds sticky rows under the header or at the bottom edge.
Overlays
The overlay layer is a stack of elements above the cells. The core paints its own layers into it, and the Overlay of each plugin joins the stack.
DataGridOverlays renders the layers in this order, with the top-most layer last:
- The selection range fills: the current range, then the stacked ranges.
- The column bands and row bands from header and marker selection.
- The
Overlayof every plugin, in array order. - The touch selection handles.
- The active-cell ring.
The active-cell ring paints above every plugin overlay, pinned segments included.
An Overlay is a React component. A state change inside it re-renders the overlay only, not the rows.
The grid adds no wrapper around an Overlay. OverlayRect paints one rectangle in view indexes and handles clamping, pinned columns, placement, and layering. It is out of the pointer path and hidden from screen readers. Put pointer work in Mount.
This plugin tints one row, found by its row id:
import {
useDataGridRowIdToViewRow,
type DataGridPlugin,
type OverlayPluginCtx,
} from "@/components/data-grid/data-grid";
import { OverlayRect } from "@/components/data-grid/data-grid-sdk";
export function createRowTint(rowId: string): DataGridPlugin {
function RowTint(ctx: OverlayPluginCtx) {
const viewRow = useDataGridRowIdToViewRow().get(rowId);
if (viewRow === undefined) return null;
const rect = { x: 0, y: viewRow, width: ctx.colCount, height: 1 };
return <OverlayRect ctx={ctx} rect={rect} className="bg-primary/10" />;
}
return { name: "row-tint", Overlay: RowTint };
}Call createRowTint once for each grid, and pass the result in plugins. OverlayRectProps also takes a style.
What ctx provides
For custom painting, read the ctx values. Give every element you paint pointer-events-none and aria-hidden="true", so it takes no clicks and a screen reader skips it. The grid renders every Overlay with the OverlayPluginCtx values as its props, so the component reads them as function MyOverlay(ctx: OverlayPluginCtx). The values let a plugin clamp a rectangle to the rendered rows, split it at pinned columns, and place it on the grid lines:
windowStartis the grid line origin of the rows canvas. It trails the first rendered row by up to 288 rows. Place a rectangle withrect.y - windowStart + 1.clampRowStartandclampRowEndare the rendered row span, from the start to the end, with the end excluded. Clamp painted rectangles to this span only.colCountis the number of visible columns. It counts real column indexes, not the scrolled column window.colOffsetis the offset to add to thexof every rectangle. When a row marker column takes the first track, it is2. Otherwise it is1.pinTrackholds the pin and track data per column. The grid always passes it. With a pinned column,hasAnyPin(pinTrack)from@/components/data-grid/data-grid-sdkreturnstrue.selectionPointernames the input that wrote the current selection:"touch","mouse","pen", or"keyboard". A touch selection shows handles at the range corners.clampRectToWindow(rect, rowStart, rowEnd, colCount)clamps a rectangle to the row range and to the columns. It returnsnullfor a rectangle outside the range.splitRectByPinZones(rect, pinTrack)splits a rectangle into up to three segments: the start zone, the unpinned zone, and the end zone. Each segment is{ rect, pin, pinStyle }.pinandpinStyleare unset in the unpinned zone.
Call clampRectToWindow first. When hasAnyPin(pinTrack) returns true and the rectangle can cross a pinned column, call splitRectByPinZones on the result. A pinned segment carries a pinStyle. Spread it into the element style. Set position: "relative", because cells have a position and a static band paints below them. Give pinned segments zIndex: GRID_LAYER.pinnedOverlaySegment, so they paint above pinned cells.
DataGridOverlays is the layer that DataGridBody renders. Its props type is DataGridOverlaysProps. A plugin does not render it.
Coordinate space
Every rectangle that an overlay paints uses view indexes. A view index is a position in the current sorted and filtered order. GridSelection.current.range uses the same space. A rectangle does not use an index into your data array, and it does not use a row id.
Two grids, or a grid and a remote peer, can disagree about sort and filter. A view index from one side is then wrong on the other. An overlay that takes coordinates from outside the grid maps a row id to a view index before it paints. Show presence shows that mapping.
Row bands
The rowBands member adds rows to the sticky top band under the header, to the sticky bottom band, or to both. It holds three members:
topandbottomare arrays of rows. They are separate fromdata, and they are not indexes into it. A missing or empty array adds no band on that side.render(ctx)paints the rows of one band. The root calls it as a plain function while it renders. A band that needs state renders a component inside the node it returns.
When several plugins add rows to one band, the root renders one segment per plugin, in array order. Each call receives a RowBandRenderCtx:
positionis"top"or"bottom".rowsholds the rows of this plugin for this band.rowOffsetcounts the rows that earlier plugins put in this band. A top band stacks from the header down. A bottom band stacks from top to bottom.ariaRowIndexBaseis thearia-rowindexof the first row of the segment. The order is the header rows, the top band, the data rows, and the bottom band.rowHeight,renderedColumns,layout,template, andheaderHeightare the layout values of the root. They line a segment up with the cell grid.headerHeightcovers the whole header block.
The rows of the bands count toward aria-rowcount and toward the sticky height of the root. Bands render during server rendering.