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.
| Symbol | Purpose | Guide |
|---|---|---|
useDataGridPinnedRows | Pins rows above or below the data rows | Pinned rows |
aggregateRow | Declares a totals row that the grid computes | Pinned rows |
serverAggregateRow | Declares a totals row from your server | Show totals from a server |
useDataGridServerAggregate | Reads totals that your server computes | Show totals from a server |
useDataGridAggregate | Reduces columns into a row | Pinned rows |
DataGridAggregateReporter | Carries the row out of the provider | Pinned 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.
| Reducer | Result |
|---|---|
"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) => unknown | Your 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
FetchAggregatesRequestis the argument offetchAggregates:spec,columnIds, andsignal.ServerAggregateStatusis"loading","stale","ready", or"error".
Related
- 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.
Context menu options
Look up the props of DataGridContextMenu and DataGridHeaderDropdown, the item ids, and the context each menu resolver receives.
Shortcut remapping options
Look up the keymap and commands props, the binding string syntax, and the options of the shortcuts dialog hook, the dialog props, and BindingChips.