Grouping

Grid supports grouping records by one or more fields with aggregation and custom footers.

 <Grid
  controller={PageController}
  records={m.records}
  style="height: 500px"
  scrollable
  border
  sortGroups
  grouping={[{ key: {}, showFooter: true }, "continent"]}
  columns={[
    {
      header: "Name",
      field: "fullName",
      sortable: true,
      aggregate: "count",
      footer: tpl(m.$group.fullName, "{0} people"),
    },
    {
      header: "Browser",
      field: "browser",
      aggregate: "distinct",
      aggregateAlias: "browsers",
      footer: tpl(m.$group.browsers, "{0} browsers"),
    },
    {
      header: "OS",
      field: "os",
      aggregate: "distinct",
      footer: tpl(m.$group.os, "{0} OS"),
    },
    {
      header: "Visits",
      field: "visits",
      align: "right",
      sortable: true,
      aggregate: "sum",
    },
  ]}
  recordAlias={m.$record}
/> 
 class PageController extends Controller {
  onInit() {
    this.store.set(m.records, [
      {
        id: 1,
        fullName: "Alice Johnson",
        continent: "North America",
        browser: "Chrome",
        os: "Windows",
        visits: 45,
      },
      {
        id: 2,
        fullName: "Bob Smith",
        continent: "North America",
        browser: "Firefox",
        os: "macOS",
        visits: 32,
      },
      {
        id: 3,
        fullName: "Carol White",
        continent: "Europe",
        browser: "Chrome",
        os: "Linux",
        visits: 28,
      },
      {
        id: 4,
        fullName: "David Brown",
        continent: "Europe",
        browser: "Safari",
        os: "macOS",
        visits: 51,
      },
      {
        id: 5,
        fullName: "Eva Green",
        continent: "Europe",
        browser: "Chrome",
        os: "Windows",
        visits: 19,
      },
      {
        id: 6,
        fullName: "Frank Wilson",
        continent: "Asia",
        browser: "Edge",
        os: "Windows",
        visits: 37,
      },
      {
        id: 7,
        fullName: "Grace Lee",
        continent: "Asia",
        browser: "Chrome",
        os: "macOS",
        visits: 42,
      },
      {
        id: 8,
        fullName: "Henry Taylor",
        continent: "North America",
        browser: "Safari",
        os: "macOS",
        visits: 25,
      },
    ]);
  }
} 
 interface Person {
  id: number;
  fullName: string;
  continent: string;
  browser: string;
  os: string;
  visits: number;
}

interface GroupData {
  $name: string;
  $level: number;
  fullName: number;
  browsers: number;
  os: number;
  visits: number;
}

interface PageModel {
  records: Person[];
  $record: Person;
  $group: GroupData;
}

const m = createModel<PageModel>(); 
 import { createModel } from "cx/data";
import { Controller, tpl } from "cx/ui";
import { Grid } from "cx/widgets"; 

Name	Browser	OS	Visits
Asia
Frank Wilson	Edge	Windows	37
Grace Lee	Chrome	macOS	42
2 people	2 browsers	2 OS	79
Europe
Carol White	Chrome	Linux	28
David Brown	Safari	macOS	51
Eva Green	Chrome	Windows	19
3 people	2 browsers	3 OS	98
North America
Alice Johnson	Chrome	Windows	45
Bob Smith	Firefox	macOS	32
Henry Taylor	Safari	macOS	25
3 people	3 browsers	2 OS	102
8 people	4 browsers	3 OS	279

Records are grouped by continent with aggregate calculations shown in the footer. Because the grid sets sortGroups, clicking the Visits header also reorders the continents by their total visits, and Name orders them by head count.

Basic Grouping

Use the grouping property to group records by a field:

<Grid
  records={m.records}
  grouping="continent"
  columns={[
    { header: "Name", field: "fullName" },
    { header: "Continent", field: "continent" },
  ]}
/>

Multi-Level Grouping

Pass an array for multiple grouping levels. The first level with an empty key groups all records (useful for totals):

grouping={[
  { key: {}, showFooter: true },  // Total row
  "continent"                      // Group by continent
]}

Aggregation

Configure aggregates on columns to calculate values per group:

columns={[
  {
    header: "Name",
    field: "fullName",
    aggregate: "count",
    footer: tpl(m.$group.fullName, "{0} people"),
  },
  {
    header: "Visits",
    field: "visits",
    aggregate: "sum",
  },
]}

Aggregate Functions

Function	Description
`count`	Count non-null values
`sum`	Sum numeric values
`avg`	Average of numeric values
`min`	Minimum value
`max`	Maximum value
`distinct`	Count unique values

Aggregate Alias

Use aggregateAlias to give the aggregate a custom name in $group:

{
  header: "Browser",
  field: "browser",
  aggregate: "distinct",
  aggregateAlias: "browsers",
  footer: tpl(m.$group.browsers, "{0} browsers"),
}

Group Captions

Use showCaption: true in the grouping configuration to display a caption row for each group. Define caption on columns to customize what appears in the caption row:

 <Grid
  controller={PageController}
  records={m.records}
  style="height: 500px"
  scrollable
  fixedFooter
  grouping={[
    { key: {}, showFooter: true },
    { key: { continent: { bind: "$record.continent" } }, showCaption: true },
  ]}
  sortGroups
  columns={[
    {
      header: "Name",
      field: "fullName",
      aggregate: "count",
      footer: tpl(m.$group.fullName, "{0} people"),
      caption: tpl(m.$group.continent, m.$group.fullName, "{0} ({1} people)"),
      sortable: true,
    },
    {
      header: "Browser",
      field: "browser",
      aggregate: "distinct",
      aggregateAlias: "browsers",
      footer: tpl(m.$group.browsers, "{0} browsers"),
      caption: tpl(m.$group.browsers, "{0} browsers"),
      sortable: true,
      sortField: "browsers",
    },
    {
      header: "Visits",
      field: "visits",
      align: "right",
      aggregate: "sum",
      caption: m.$group.visits,
      sortable: true,
    },
  ]}
  recordAlias={m.$record}
/> 
 class PageController extends Controller {
  onInit() {
    this.store.set(m.records, [
      {
        id: 1,
        fullName: "Alice Johnson",
        continent: "North America",
        browser: "Chrome",
        visits: 45,
      },
      {
        id: 2,
        fullName: "Bob Smith",
        continent: "North America",
        browser: "Firefox",
        visits: 32,
      },
      {
        id: 3,
        fullName: "Carol White",
        continent: "Europe",
        browser: "Chrome",
        visits: 28,
      },
      {
        id: 4,
        fullName: "David Brown",
        continent: "Europe",
        browser: "Safari",
        visits: 51,
      },
      {
        id: 5,
        fullName: "Eva Green",
        continent: "Europe",
        browser: "Chrome",
        visits: 19,
      },
      {
        id: 6,
        fullName: "Frank Wilson",
        continent: "Asia",
        browser: "Edge",
        visits: 37,
      },
      {
        id: 7,
        fullName: "Grace Lee",
        continent: "Asia",
        browser: "Chrome",
        visits: 42,
      },
      {
        id: 8,
        fullName: "Henry Taylor",
        continent: "North America",
        browser: "Safari",
        visits: 25,
      },
    ]);
  }
} 
 interface Person {
  id: number;
  fullName: string;
  continent: string;
  browser: string;
  visits: number;
}

interface GroupData {
  $name: string;
  $level: number;
  continent: string;
  fullName: number;
  browsers: number;
  visits: number;
}

interface PageModel {
  records: Person[];
  $record: Person;
  $group: GroupData;
}

const m = createModel<PageModel>(); 
 import { createModel } from "cx/data";
import { Controller, tpl } from "cx/ui";
import { Grid } from "cx/widgets"; 

Name	Browser	Visits
Asia (2 people)	2 browsers	79
Frank Wilson	Edge	37
Grace Lee	Chrome	42
Europe (3 people)	2 browsers	98
Carol White	Chrome	28
David Brown	Safari	51
Eva Green	Chrome	19
North America (3 people)	3 browsers	102
Alice Johnson	Chrome	45
Bob Smith	Firefox	32
Henry Taylor	Safari	25
8 people	4 browsers	279

Per-Group Row Numbers

Add a column with the built-in cxe-grid-row-number class to display automatic row numbers. By default these count continuously across the whole grid. Set resetRowNumbers: true on a grouping level to restart numbering from 1 at the beginning of each group:

 <Grid
  controller={PageController}
  records={m.records}
  sortField="visits"
  sortDirection="DESC"
  grouping={[
    {
      key: { continent: m.$record.continent },
      showCaption: true,
      resetRowNumbers: true,
    },
  ]}
  columns={[
    {
      header: "#",
      defaultWidth: 50,
      align: "right",
      children: <div class="cxe-grid-row-number" />,
    },
    {
      header: "Name",
      field: "fullName",
      caption: m.$group.continent,
    },
    { header: "Visits", field: "visits", align: "right" },
  ]}
  recordAlias={m.$record}
/> 
 class PageController extends Controller {
  onInit() {
    this.store.set(m.records, [
      {
        id: 1,
        fullName: "Alice Johnson",
        continent: "North America",
        visits: 45,
      },
      { id: 2, fullName: "Bob Smith", continent: "North America", visits: 32 },
      {
        id: 3,
        fullName: "Henry Taylor",
        continent: "North America",
        visits: 25,
      },
      { id: 4, fullName: "Carol White", continent: "Europe", visits: 28 },
      { id: 5, fullName: "David Brown", continent: "Europe", visits: 51 },
      { id: 6, fullName: "Eva Green", continent: "Europe", visits: 19 },
      { id: 7, fullName: "Frank Wilson", continent: "Asia", visits: 37 },
      { id: 8, fullName: "Grace Lee", continent: "Asia", visits: 42 },
    ]);
  }
} 
 interface Person {
  id: number;
  fullName: string;
  continent: string;
  visits: number;
}

interface GroupData {
  $name: string;
  $level: number;
  continent: string;
  fullName: number;
}

interface PageModel {
  records: Person[];
  $record: Person;
  $group: GroupData;
}

const m = createModel<PageModel>(); 
 import { createModel } from "cx/data";
import { Controller, tpl } from "cx/ui";
import { Grid } from "cx/widgets"; 

#	Name	Visits
	Asia
	Grace Lee	42
	Frank Wilson	37
	Europe
	David Brown	51
	Carol White	28
	Eva Green	19
	North America
	Alice Johnson	45
	Bob Smith	32
	Henry Taylor	25

The counter resets on the group caption row, so the grouping level needs a caption (showCaption or caption) for the reset to take effect.

Sorting Groups

By default groups are ordered by their key, ascending. There are three ways to change that.

Sort by an aggregate or key declaratively. Set sortField (and optionally sortDirection) on a grouping level. The field is resolved against the group’s key fields, aggregate aliases and $name, so an aggregate alias sorts groups by that aggregate:

grouping={[
  {
    key: { continent: { bind: "$record.continent" } },
    sortField: "visits",     // aggregate alias
    sortDirection: "DESC",   // highest total first
  },
]}

Use a sorters array for multi-field group sorting ([{ field, direction }, ...]). A custom comparer still takes precedence over both.

Sort groups by clicking column headers. Set sortGroups on the grid. When the user sorts a column whose field is a group key or aggregate, the groups reorder to match; sorting any other column leaves the group order untouched. This is ignored when preserveGroupOrder is set.

<Grid sortGroups grouping={["continent"]} columns={[ /* sortable columns */ ]} />

Group Data

The $group object contains:

Property	Description
`$name`	Group name/label
`$level`	Nesting level (0 for deepest)
`$records`	Records in the group
`$key`	Serialized group key
`[field]`	Aggregate value for each field

Grouping Configuration

Property	Type	Description
`key`	`object`	Fields to group by. Empty object groups all records.
`showHeader`	`boolean`	Show group header row.
`showFooter`	`boolean`	Show group footer row.
`showCaption`	`boolean`	Show group caption.
`resetRowNumbers`	`boolean`	Restart `cxe-grid-row-number` numbering from 1 at the start of each group at this level. Requires a caption.
`caption`	`StringProp`	Caption template.
`text`	`StringProp`	Group name template.
`sortField`	`string`	Sort groups by this field, resolved against the group’s key fields, aggregate aliases and `$name`.
`sortDirection`	`string`	Sort direction for `sortField` (`ASC` or `DESC`). Defaults to `ASC`.
`sorters`	`array`	Multi-field group sorting: `[{ field, direction }, ...]`.
`comparer`	`function`	Custom group comparer. Takes precedence over `sortField`/`sorters`.