Pinned rows

Wiring it up

useDataGridPinnedRows() is a single hook. Call it in your own component ABOVE where you render <DataGridProvider>. The plugins prop lives on the provider, so the plugin has to exist before it. The same composition works with the core's DataGrid convenience wrapper (see the note on Fill handle).

"use client";

import { DataGrid } from "@/components/data-grid/data-grid";
import { useDataGridPinnedRows } from "@/components/data-grid-pinned-rows/data-grid-pinned-rows";

function MyGrid() {
  const { plugin } = useDataGridPinnedRows({ topRows: [totalsRow] });

  return <DataGrid data={data} columns={columns} getRowId={getRowId} plugins={[plugin]} />;
}

API

useDataGridPinnedRows({ topRows?, bottomRows? }) accepts a separate array from data, not indices into it, for each band. Each band renders every row in the array, in order, so a band can stack more than one row. The demo above pins an averages row on top and a totals row on the bottom. Pinned rows keep the viewIndex, sort, filter, and selection machinery untouched.

Cells render through the same DataGridCell and cell-type pipeline as data rows: the same column alignment, the same text, number, date, and other formatting, and the same subgrid column tracks. So a pinned row lines up with its columns pixel-for-pixel, including pinned-left and pinned-right columns and column resize.

Pinned rows go through the grid's getRowId, so ctx.rowId in a pinned cell is that id. If getRowId throws on a pinned row or returns an empty or non-string value, the row gets a band id instead. The band id is __pinned-top-<index> or __pinned-bottom-<index>, where <index> is the row's position in its band.

Computing a totals row

const TOTALS_SPECS: AggregateSpecs = { score: "sum", age: "avg" };

function MyGrid() {
  const grid = useDataGridState(initialRows, { getRowId: (r) => r.id });
  const [totals, setTotals] = useState({ id: "__totals__" });

  // Stable identity: keep `onChange` out of the inline-closure pattern, and keep the band
  // arrays memoized so the plugin only changes when the totals actually do.
  const onTotalsChange = useCallback((row: Record<string, unknown>) => {
    setTotals((prev) => ({ ...prev, ...row }));
  }, []);

  const bottomRows = useMemo(() => [totals], [totals]);
  const { plugin } = useDataGridPinnedRows({ bottomRows });
  const plugins = useMemo(() => [...grid.plugins, plugin], [grid.plugins, plugin]);

  return (
    <DataGridProvider {...grid} columns={columns} plugins={plugins}>
      <DataGridAggregateReporter specs={TOTALS_SPECS} onChange={onTotalsChange} />
      <DataGridRoot>
        <DataGridHeader />
        <DataGridBody />
      </DataGridRoot>
    </DataGridProvider>
  );
}

useDataGridAggregate(specs) reduces each columnId in specs over the grid's filtered/sorted/ searched viewIndex. It returns a { [columnId]: value } object: the row shape useDataGridPinnedRows's topRows/bottomRows expect, since pinned cells resolve values through each column's accessorKey/accessorFn like data rows do. A reducer is "sum", "avg", "min", "max", "count", or a custom (values, rows) => unknown function. Numeric reducers skip null/undefined values instead of producing NaN. count counts non-empty values. Pass scope: "all" to reduce over the raw data array instead, ignoring the active filter. If a specs key matches no column id, the aggregate ignores it and a dev warning fires once.

Because the hook reads the store and the plugins prop lives on the provider, DataGridAggregateReporter bridges the two: it renders as a plain child under the provider and reports the result through onChange into parent state, which is what feeds topRows/bottomRows.

Custom reducers

A reducer function receives every resolved value and its source row, unfiltered. Write your own empty-handling if the built-ins don't fit. The hook is generic over the row type: when specs carries it (as AggregateSpecs<Row> here, or as the generic at the hook call), rows is typed:

const specs: AggregateSpecs<Row> = {
  name: (_values, rows) => `${rows.length} rows`,
  score: (_values, rows) => Math.max(...rows.map((r) => r.score), 0),
};

Manual computation

For anything useDataGridAggregate doesn't cover, compute the band's rows yourself from grid.data in a useMemo. Reducing over grid.data ignores the active filter. Reduce over useDataGridViewIndex() instead, if the band must match what the filtered view shows.

function computeTotalsRow(rows: readonly Row[]): Row {
  return {
    id: "__totals__",
    name: `${rows.length} rows`,
    score: rows.reduce((sum, r) => sum + r.score, 0),
    // ...
  };
}

const top = useMemo(() => [computeTotalsRow(grid.data)], [grid.data]);