gridcn2.0.0
Rows, pages, and menus

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.

Name
Email
Age
Role
Score
Silent Tiger
user0@example.com
63
Viewer
4
Quick Lion
user1@example.com
67
Viewer
89
Swift Wolf
user2@example.com
40
Manager
80
Eager Lion
user3@example.com
50
User
51
Eager Tiger
user4@example.com
45
Viewer
83
Silent Wolf
user5@example.com
24
User
15
Swift Lion
user6@example.com
34
Viewer
62
Eager Lion
user7@example.com
21
Manager
42
Eager Eagle
user8@example.com
25
Editor
35
Bold Tiger
user9@example.com
19
Editor
52
Bold Bear
user10@example.com
42
User
28
Swift Wolf
user11@example.com
47
Manager
9
Swift Bear
user12@example.com
41
Viewer
45
Eager Wolf
user13@example.com
35
Editor
44
Swift Eagle
user14@example.com
65
Viewer
51
Quick Lion
user15@example.com
22
Manager
28
Bold Wolf
user16@example.com
30
Editor
76
Swift Eagle
user17@example.com
19
Admin
26
Eager Eagle
user18@example.com
35
Manager
70
Eager Bear
user19@example.com
33
Editor
67
Silent Lion
user20@example.com
48
Manager
89
Silent Tiger
user21@example.com
62
Manager
40
Eager Tiger
user22@example.com
51
Manager
82
Silent Lion
user23@example.com
26
Admin
16
Bold Eagle
user24@example.com
26
Admin
38
Bold Lion
user25@example.com
49
Viewer
3
Quick Tiger
user26@example.com
26
Viewer
41
Bold Eagle
user27@example.com
50
Editor
10
Swift Tiger
user28@example.com
55
Editor
6
Silent Lion
user29@example.com
35
Viewer
42
39.5
Average
44.13333333333333
30 rows
1185
Total
1324
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 readOnly to false or to a function that returns false for the row, its cells carry data-readonly. A column with accessorFn and no accessorKey or setValue always 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

PropTypeDefault
topRowsreadonly unknown[]none
bottomRowsreadonly unknown[]none
statusServerAggregateStatusthe status of the serverAggregateRow entries, else "ready"

status marks both bands while server values load, go stale, or fail. See Pinned rows options.

PropTypeDefault
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. defaultPageSize pages the view of the whole array. useDataGridAggregate totals every row that the filter leaves, not one page. Pass scope: "page" to total the shown page only.
  • Server pagination. data is the current page, so useDataGridAggregate covers that page.
  • Scroll mode. Unloaded rows are undefined holes. 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.

On this page