gridcn2.0.0
Add-on optionsRows, pages, and menus

Pinned rows options

Look up the options of useDataGridPinnedRows, aggregateRow, serverAggregateRow, and useDataGridAggregate, plus the reducers and the reporter props.

useDataGridPinnedRows returns a plugin that pins rows above or below the data rows. aggregateRow and serverAggregateRow declare a totals row that the band computes. useDataGridAggregate reduces columns into a row, and DataGridAggregateReporter carries that row out of the provider. The rules for pinned rows are on Pinned rows.

SymbolPurposeGuide
useDataGridPinnedRowsPins rows above or below the data rowsPinned rows
aggregateRowDeclares a totals row that the grid computesPinned rows
serverAggregateRowDeclares a totals row from your serverShow totals from a server
useDataGridServerAggregateReads totals that your server computesShow totals from a server
useDataGridAggregateReduces columns into a rowPinned rows
DataGridAggregateReporterCarries the row out of the providerPinned rows

useDataGridPinnedRows

Prop

Type

The result is { plugin, serverAggregates }, typed UseDataGridPinnedRowsResult. Pass the plugin in plugins. serverAggregates lists the result of each serverAggregateRow entry. The plugin keeps its identity while the entries of topRows and bottomRows and the status stay equal. A row object counts by identity. An aggregateRow or serverAggregateRow counts by its content, so an inline array and an inline aggregateRow are fine.

status

status marks both bands while server values load, go stale, or fail. The bands dim and set data-status. They set aria-busy only while values load or go stale. The default is the status of the serverAggregateRow entries of the band, else "ready".

Totals rows

aggregateRow and serverAggregateRow declare a totals row for topRows or bottomRows.

aggregateRow

aggregateRow(specs, options) returns a pinned row that reduces specs over the grid rows. Put it in topRows or bottomRows. The band reads each value by column id, so a column needs no accessorKey that equals its id. An inline reducer function keeps the band. The band calls the newest one when it next reduces.

Prop

Type

serverAggregateRow

serverAggregateRow(options) returns a pinned row whose values come from your server. It takes the options of useDataGridServerAggregate and sets the status of the bands. With the default refreshAfterSave, it fetches again after the last pending save settles. A serverAggregateRow pinned in two places fetches twice, and development builds warn once.

Prop

Type

useDataGridServerAggregate

useDataGridServerAggregate(options) and DataGridServerAggregateReporter (the same options plus onChange) show totals that your server computes. The steps are on Show totals from a server.

Prop

Type

The result is a ServerAggregateResult:

Prop

Type

useDataGridAggregate

useDataGridAggregate(specs, options) takes a specs object with one reducer for each column id. It returns a { [columnId]: value } object. Use it to read the totals inside the provider. It recomputes when the view index, the data, the scope, or an entry of specs changes. It compares a named reducer by its name and a reducer function by its identity.

An inline specs object of named reducers keeps its result. A reducer function in the render recomputes on every render. To skip that work, define the function at module scope or memoize it.

Prop

Type

Reducers

A reducer has the type AggregateReducer: a name or a function.

ReducerResult
"sum", "avg", "min", "max"The reducer uses finite numbers only. It skips numeric strings, NaN, dates, null, and undefined. With no number left, the result is null.
"count"The number of values that are not null, undefined, or ""
(values, rows) => unknownYour result. values holds every resolved value, empty ones included. rows holds the source rows.

The grid resolves values through accessorKey or accessorFn, so a computed column aggregates correctly. The result uses column ids as keys. aggregateRow shows it in the band. See Totals row. The hook ignores a key of specs that matches no column id, and development builds warn once. scope: "view" (default) covers every row that the sort and filter leave, all pages of a client-paged grid.

scope: "page" covers the shown page only. With server pagination, the grid holds one page, so the aggregate covers that page. In scroll mode, the reducers skip unloaded rows, and development builds warn once. Take totals for the whole result from your server.

DataGridAggregateReporter

The reporter sits inside the provider and calls onChange with the row, so a component outside the provider can show it. It renders nothing.

Prop

Type

onChange can change identity on every render. After the row changes, the reporter calls the newest one.

Example

This sample pins a sum of price to the bottom of the grid:

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

type Row = { id: string; item: string; price: number };

const rows: Row[] = [
  { id: "1", item: "Pen", price: 2 },
  { id: "2", item: "Ink", price: 8 },
];
const columns = defineColumns<Row>()([
  { id: "item", header: "Item", accessorKey: "item" },
  { id: "price", header: "Price", accessorKey: "price", type: "number" },
]);
const TOTALS = aggregateRow<Row>(
  { price: "sum" },
  { cells: { id: "total", item: "Total" } },
);

export function PricesGrid() {
  const { plugin } = useDataGridPinnedRows({ bottomRows: [TOTALS] });

  return (
    <DataGrid
      defaultData={rows}
      columns={columns}
      plugins={[plugin]}
      className="h-80"
    />
  );
}

The bottom band shows "Total" and 10. A filter that hides the first row changes the band to 8, because scope defaults to "view".

Server totals types

  • FetchAggregatesRequest is the argument of fetchAggregates: spec, columnIds, and signal.
  • ServerAggregateStatus is "loading", "stale", "ready", or "error".
  • Pinned rows: the display-only rules, the geometry, and the server limits.
  • Client pagination: totals cover every page, and scope: "page" totals the shown page.
  • Plugin model: how a plugin enters the grid.

On this page