gridcn2.0.0
Rows, pages, and menus

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.

A long list reads better when rows that share a value sit together. groupBy names the columns. The grid heads each row group with a group row. The group row shows the key, the row count, and one reduced value for each aggregate column. A group row opens and closes.

Name
Role
Active
Age
Score
pnpm dlx shadcn@latest add @gridcn/data-grid-row-grouping-demo

Group the rows

Set groupBy to column ids, outermost first. A grid with no groupBy is unchanged. groupable: false keeps a column out of the group menu, and aggregate sets the reducer that a group row shows for the column:

import { DataGrid, defineColumns } from "@/components/data-grid/data-grid";

type Row = { id: string; region: string; city: string; sales: number };

const columns = defineColumns<Row>()([
  { id: "region", header: "Region", accessorKey: "region" },
  { id: "city", header: "City", accessorKey: "city" },
  {
    id: "sales",
    header: "Sales",
    accessorKey: "sales",
    type: "number",
    aggregate: "sum",
  },
]);

const rows: Row[] = [{ id: "1", region: "North", city: "Oslo", sales: 12 }];

function SalesGrid() {
  return (
    <DataGrid
      defaultData={rows}
      columns={columns}
      defaultGroupBy={["region", "city"]}
    />
  );
}

A grid takes at most four group levels. An unknown column, a groupable: false column, and a repeated column drop out of groupBy. A group key is the stored value. null, undefined, and "" form one empty group that reads labels.grouping.empty.

Control the groups

PropTypeDefault
groupByreadonly string[]Uncontrolled
defaultGroupByreadonly string[] or a function[]
onGroupByChange(next) => voidNone
expanded{ mode, ids }Uncontrolled
defaultExpanded{ mode, ids }Every group closed
onExpandedChange(next) => voidNone
renderGroupLabel(ctx) => ReactNodelabels.grouping.rowLabel: column: key (count)

ExpandedState is { mode: "collapsed" | "expanded", ids }. The ids are the groups that differ from mode. Read the group ids from onExpandedChange. Pass a stable renderGroupLabel.

The actions setGroupBy, toggleGroupBy, setExpanded, toggleGroup, expandAll, and collapseAll change the groups. A server grid answers each of them with { ok: false, reason: "server-groups" } when the server lays out the groups.

Keys and menus

On a group row:

KeyResult
Enter, SpaceOpens a closed group and closes an open one.
ArrowRightOpens a closed group. Otherwise moves right.
ArrowLeftCloses an open group. Otherwise moves left.

Right-to-left layouts mirror the arrows. The keymap actions are toggleGroupRow, expandGroupRow, and collapseGroupRow. The context menu adds Group by and Ungroup to the header menu and a menu to each group row. The live region reads labels.grouping.expanded, collapsed, and loadFailed.

While the grid groups, it takes the role treegrid. The row marker numbers each row inside its innermost group. Export, find and replace, fill, comments, the status bar, and useDataGridAggregate read rows and skip group rows. A group row holds no data, so a row operation that starts on one reports the reason "group-row". Read a view row through dataIndexAt: viewIndex holds an entry below 0 for a group row.

Pages of groups

With pageSize set, a page holds pageSize top-level groups with the rows opened under them. pager.unit is "groups", and the footer reads labels.pagination.rangeGroups. A change of groupBy returns to page 1. See Client pagination.

Group in the URL and in saved views

URL state writes groupBy as the group param. A saved view keeps groupBy. The open groups stay out of both.

Server mode

useDataGridServerRows groups on your server when the spec holds groupBy. The grid never holds every row. The server sends one list at a time: the groups of one level, or the rows of one group. Each request names the list with groupPath and childKind. The hook works in scroll mode and in pages mode. In pages mode the top level is one page of groups.

The server answers childKind: "groups" with groups, groupCount, and, at the top level, totalRowCount. It answers childKind: "rows" with the rows of one group. Group server rows lists the request, the answer, and the checks.

  • The core shows the group rows of groupLayout and never buckets rows (groupMode="server"). The hook sets both props.
  • While the server lays out the groups, an insert, a duplicate, a delete, and a move report the reason server-groups.
  • A save, a refusal, and refresh() keep the open groups in place.
  • A save of an aggregate column reloads only the group rows above the saved row. A save of another column that no group, sort, or aggregate uses sends no request. A save of a group or sort column, or any save while a filter or search is active, reloads every open list.
  • A swap between a grouped and an ungrouped source ends an open edit. onEditEnd reports result: "cancel".
  • selectAllMatching() counts the rows of the result that totalRowCount reports.
  • The query layer answers group requests for Drizzle and Kysely. See Query layer.

Limits

  • The group queries of the query layer have no performance measurement.
  • At most 10,000 groups stay open. A further toggle shows labels.grouping.tooManyOpen.

On this page