gridcn2.0.0
Selection and shortcuts

Status bar

Show count, sum, avg, min, and max of the selected cells under the grid with the data-grid-status-bar add-on.

Users read totals of a selection without exporting it. data-grid-status-bar computes them from the grid's own data. <DataGridStatusBar /> renders the bar, and useDataGridSelectionStats is the headless hook. Both read committed values only, never the draft of an open editor, and write nothing, so readOnly grids work unchanged. For a total of a whole column that stays in sight, use a pinned totals row.

Select a range — Shift+click, a row header, or a column header — and the bar below aggregates the selection.

Name
Age
Score
Silent Tiger
63
4
Quick Lion
67
89
Swift Wolf
40
80
Eager Lion
50
51
Eager Tiger
45
83
Silent Wolf
24
15
Swift Lion
34
62
Eager Lion
21
42
Eager Eagle
25
35
Bold Tiger
19
52
Bold Bear
42
28
Swift Wolf
47
9
Swift Bear
41
45
Eager Wolf
35
44
Swift Eagle
65
51
Quick Lion
22
28
Bold Wolf
30
76
Swift Eagle
19
26
Eager Eagle
35
70
Eager Bear
33
67
Silent Lion
48
89
Silent Tiger
62
40
Eager Tiger
51
82
Silent Lion
26
16
Bold Eagle
26
38
Bold Lion
49
3
Quick Tiger
26
41
Bold Eagle
50
10
Swift Tiger
55
6
Silent Lion
35
42
pnpm dlx shadcn@latest add @gridcn/data-grid-status-bar

The data-grid-status-bar item depends on the shadcn button component. Place the bar inside DataGridProvider, next to DataGridRoot:

import {
  DataGridBody,
  DataGridHeader,
  DataGridProvider,
  DataGridRoot,
  defineColumns,
} from "@/components/data-grid/data-grid";
import {
  DataGridStatusBar,
} from "@/components/data-grid-status-bar/data-grid-status-bar";

type Sale = { id: string; region: string; amount: number };

const columns = defineColumns<Sale>()([
  { id: "region", header: "Region", accessorKey: "region", type: "text" },
  { id: "amount", header: "Amount", accessorKey: "amount", type: "number" },
] as const);

export function SalesGrid({ sales }: { sales: Sale[] }) {
  return (
    <DataGridProvider data={sales} columns={columns}>
      <DataGridRoot className="h-80">
        <DataGridHeader />
        <DataGridBody />
      </DataGridRoot>
      <DataGridStatusBar />
    </DataGridProvider>
  );
}

Which cells count

The bar aggregates the union of every selection channel: the primary range, the stacked Ctrl/Cmd+click ranges, whole-row selections, and whole-column selections. A cell that sits in two channels counts once. Hidden columns and filtered-out rows are outside the view, so they never count. With client pagination, the grid keeps every row, but a selection covers the shown page only. So the bar aggregates the cells of that page.

Which values count

A cell counts as numeric if its raw value is a finite number. Detection reads the value, so a custom numeric cell type aggregates without configuration. count counts the non-empty cells, where empty means that the isEmpty of the column's cell type returns true. sum, avg, min, and max run over the numeric cells. The sum uses Neumaier compensated summation to limit floating-point error.

Display and formatting

The aggregates show once the selection covers two cells whose value is not undefined. A null cell or an empty-text cell has a value, so it counts toward the two cells. count shows with the others. sum, avg, min, and max show only with a numeric cell in the selection.

When every numeric cell comes from one column, the toDisplayText of that column formats sum, avg, min, and max. A number column with a format option uses that format, for example currency or percent. A number column with decimals and no format rounds to decimals and groups digits by locale. A number column with neither uses the format of the bar, like numeric cells that span several columns. That format is Intl.NumberFormat with maximumFractionDigits: 4 in the locale of the grid. formatValue overrides all of these.

The bar also shows the count of hidden checked rows as (+3 hidden), and the select-all banner of a server grid. With nothing to show and no children, it renders nothing.

Server mode

The unloaded rows of a lazy source in scroll mode have no value and count as nothing. A grid with totalRowCount, or with pageSize, shows a select-all banner when every row of the page is checked and the result is larger. The banner needs checkedRowsLifetime="across-filters", which is the default with totalRowCount. The banner offers "Select all 237 matching", or "Select all matching" when the size is null. After the click, it reads "All 237 selected." with a "Clear selection" button. selectAllMatching() announces the real count in the live region, or "All matching rows checked" when the size is null.

Set the banner text with labels.statusBar.pageSelected, selectAllMatching, allSelected, and clearSelection. selectAllMatching and allSelected take null for an unknown size.

When it computes

A selection whose ranges cover up to 5,000 cells computes at once. A larger selection computes 150 ms after the last change, so dragging a large range does not walk the whole selection on every frame.

A walk stops at 200,000 cells (MAX_STATUS_CELLS). Above the cap, every value gets a ≈ prefix, and the title of the bar says how many cells the values cover.

Headless hook

useDataGridSelectionStats() returns the numbers for your own UI. Call it inside DataGridProvider:

import {
  useDataGridSelectionStats,
} from "@/components/data-grid-status-bar/data-grid-status-bar";

export function SelectionSum() {
  const { sum, approximate } = useDataGridSelectionStats();

  const prefix = approximate ? "≈" : "";

  return <span>{sum === null ? "No numbers" : `${prefix}${sum}`}</span>;
}

The result holds cells, count, numeric, sum, avg, min, max, numericColumnId, and approximate. The aggregates are null without numeric cells. numericColumnId is null if the numeric cells span several columns.

Props

PropTypeDefaultDescription
aggregatesreadonly ("count" | "sum" | "avg" | "min" | "max")[]all five, in this orderWhich aggregates to show, and in which order.
formatValue(value: number, aggregate: StatusBarAggregate) => stringthe single-column rule, else the Intl defaultFormats the shown aggregate values.
labelsPartial<DataGridStatusBarLabels>merged over labels.statusBarOverrides the strings of this bar.
classNamestringnoneExtra classes on the bar element.
childrenReactNodenoneExtra items, rendered after the aggregates. The bar stays visible while it has children.

The bar is a polite live region

The bar is role="status" with aria-live="polite" and aria-atomic="true". Each value sits next to its label, for example "Sum 1,234".

On this page