Pinned rows
Pin rows to the top or bottom edge of the grid, such as a totals row, and compute their values from the rows that the view shows.
A totals or averages row must stay in sight while the data rows scroll. useDataGridPinnedRows pins one band of rows under the header and one band at the bottom edge of the viewport. Data rows scroll underneath both bands. The same add-on computes sums and averages over the rows that the view shows. The header row stays fixed without this add-on. See Column headers and groups.
Filter the Role column via the toolbar: the pinned Average and Total rows recompute over only the rows the filter leaves visible, not the full dataset.
pnpm dlx shadcn@latest add @gridcn/data-grid-pinned-rows
Pin rows
The hook returns one plugin. Pass the plugin to the grid through plugins. Each band takes its own array of rows, separate from data:
import { DataGrid, defineColumns } from "@/components/data-grid/data-grid";
import { useDataGridPinnedRows } from "@/components/data-grid-pinned-rows/data-grid-pinned-rows";
type Row = { id: string; item: string; price: number };
const columns = defineColumns<Row>()([
{ id: "item", header: "Item", accessorKey: "item" },
{ id: "price", header: "Price", accessorKey: "price", type: "number" },
]);
const rows: Row[] = [
{ id: "1", item: "Pen", price: 2 },
{ id: "2", item: "Ink", price: 8 },
];
const bottomRows = [{ id: "total", item: "Total", price: 10 }];
function PricesGrid() {
const { plugin } = useDataGridPinnedRows({ bottomRows });
return <DataGrid defaultData={rows} columns={columns} plugins={[plugin]} />;
}A band renders every row of its array in order, so a band can stack several rows. Pinned cells use the cell type of their column, so alignment and formatting match the data rows. They follow the column tracks, so pinned columns and column resize apply to them.
Pinned row behavior
A pinned row is display-only. It is not part of data or the view index. As a result:
- It never sorts or filters. It stays in the order that you pass.
- It never joins the selection. A click on it does nothing, and it never becomes the active cell.
- It has no tab stop, and arrow keys skip it.
- Unless the column sets
readOnlytofalseor to a function that returnsfalsefor the row, its cells carrydata-readonly. A column withaccessorFnand noaccessorKeyorsetValuealways carries it.
A pinned row goes through the getRowId of the grid, so ctx.rowId in a pinned cell is that id. If getRowId throws or returns an empty or non-string value, the row gets a band id. The band id is __pinned-top-<index> or __pinned-bottom-<index>, where <index> is the position of the row in its band.
Totals row
The shortest totals row sums your data in a useMemo:
import { useMemo } from "react";
import { DataGrid, defineColumns } from "@/components/data-grid/data-grid";
import { useDataGridPinnedRows } from "@/components/data-grid-pinned-rows/data-grid-pinned-rows";
type Row = { id: string; item: string; price: number };
const columns = defineColumns<Row>()([
{ id: "item", header: "Item", accessorKey: "item" },
{ id: "price", header: "Price", accessorKey: "price", type: "number" },
]);
function TotalsGrid({ rows }: { rows: Row[] }) {
const bottomRows = useMemo(() => {
const price = rows.reduce((sum, row) => sum + row.price, 0);
return [{ id: "total", item: "Total", price }];
}, [rows]);
const { plugin } = useDataGridPinnedRows({ bottomRows });
return <DataGrid data={rows} columns={columns} plugins={[plugin]} />;
}This total covers every row of rows and ignores the active filter. To total the rows that the view shows, use aggregateRow.
aggregateRow(specs, options) builds a pinned row that reduces the columns that specs names over the rows of the view. Put it in topRows or bottomRows. The band computes it inside the grid, so the sample needs no state and no reporter. The row reads each value by column id. The cells option sets fixed values by column id, such as the id and a label. A computed value replaces a fixed cell of the same column id:
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 columns = defineColumns<Row>()([
{ id: "item", header: "Item", accessorKey: "item" },
{ id: "price", header: "Price", accessorKey: "price", type: "number" },
]);
const rows: Row[] = [
{ id: "1", item: "Pen", price: 2 },
{ id: "2", item: "Ink", price: 8 },
];
const TOTALS = aggregateRow<Row>(
{ price: "sum" },
{ cells: { id: "total", item: "Total" } },
);
function TotalsGrid() {
const { plugin } = useDataGridPinnedRows({ bottomRows: [TOTALS] });
return <DataGrid defaultData={rows} columns={columns} plugins={[plugin]} />;
}The hook keeps the plugin while the entries of topRows and bottomRows stay equal. It compares a plain row object by its own values, and an aggregateRow by its specs, scope, and cells. An inline aggregateRow({ qty: "sum" }) keeps the plugin and the band. A new reducer function in an inline aggregateRow makes the band reduce again.
A reducer is "sum", "avg", "min", "max", "count", or a function. The numeric reducers use finite numbers only, so they skip numeric strings and dates. count counts the values that are not null, undefined, or "". A reducer with no counted value gives null, and count gives 0. A function receives every value, so use one for dates or numeric strings. The aggregate ignores a spec key that matches no column id and warns once in development. The group rows of row grouping follow the same rules.
Custom reducers
A reducer function receives every resolved value, empty ones included, and the source rows. It owns its own empty handling. Type the specs as AggregateSpecs<Row>, or pass Row to aggregateRow<Row>, to type rows:
import type { AggregateSpecs } from "@/components/data-grid-pinned-rows/data-grid-pinned-rows";
type Row = { id: string; item: string; price: number };
const specs: AggregateSpecs<Row> = {
item: (_values, rows) => `${rows.length} rows`,
price: (_values, rows) =>
rows.reduce((max, row) => Math.max(max, row.price), 0),
};Totals outside the band
useDataGridAggregate(specs) returns the same { [columnId]: value } object inside the grid provider. DataGridAggregateReporter reports that object through onChange to state of the parent. Use them to show a total outside the band, for example in a toolbar. A plain row object in a band reads its cells through each accessorKey or accessorFn, as a data row does. A result object therefore shows a total only where accessorKey equals the column id. aggregateRow reads each value by column id and has no such limit.
Own totals
For anything else, compute the band rows yourself in a useMemo, as the first sample does. If the band must match the filtered view, reduce over useDataGridViewIndex(). When the grid pages its view, that hook holds the shown page only.
Options
| Prop | Type | Default |
|---|---|---|
topRows | readonly unknown[] | none |
bottomRows | readonly unknown[] | none |
status | ServerAggregateStatus | the status of the serverAggregateRow entries, else "ready" |
status marks both bands while server values load, go stale, or fail. See Pinned rows options.
| Prop | Type | Default |
|---|---|---|
scope | "view" | "page" | "all" | "view" |
scope: "view" reduces over the rows that the filter and sort leave visible. scope: "page" reduces over the shown page. scope: "all" reduces over all of data, filter ignored.
Geometry
The top band shrinks the space above the data rows, like the header. The bottom band shrinks the bottom of the viewport. Both work with row virtualization and with useDataGridScrollToCell, so keyboard navigation never scrolls a data row under a band. A column pinned to the start side or the end side stays fixed inside a band.
Each band casts a soft shadow on the edge that faces the data rows. The shadow appears only after a data row scrolls beneath the band. It uses the --grid-pin-shadow token.
Accessibility
The aria-rowindex order is: header rows, pinned-top rows, data rows, pinned-bottom rows. aria-rowcount includes both bands. Pinned cells carry role="gridcell", data-type, and data-readonly like data cells. They carry no tabindex and no aria-selected.
Server mode
Aggregates reduce the rows that the grid holds in memory. Three data modes set that scope:
- Client pagination.
defaultPageSizepages the view of the whole array.useDataGridAggregatetotals every row that the filter leaves, not one page. Passscope: "page"to total the shown page only. - Server pagination.
datais the current page, souseDataGridAggregatecovers that page. - Scroll mode. Unloaded rows are
undefinedholes. The aggregate skips them and warns once in development, so the band covers loaded rows only.
serverAggregateRow gives the totals of the whole server result. It asks your server for the totals of the current filter and search. See Show totals from a server.
With filterMode="server" or sortMode="server", the view holds the rows of the answer, so scope: "view" covers exactly those rows.
Related
- Pinned rows options: the full option list
- Show totals from a server: totals of the whole result
- Client pagination: totals under paging
- Column order and pinning: pinned columns inside a band
Row markers
Add a row-number, checkbox, or drag-handle column at the start of the grid, and replace its cells and its header with your own content.
Row grouping
Group rows by one or more columns into row groups that open and close, with a count and a reduced value on each group row, on a local array or on your server.