experiment_id: web-retrieval-v1
fixture_id: /docs/features/row-grouping
mode: provenance
representation: html
origin_response_id: f89728dfb51932158e1d80df30709b01
version: 2026-10-21
version_created_at_utc: 2026-10-21T20:42:35.700Z
version_nonce: 807482af5077b64799a93402eec1796a
generated_at_utc: 2026-10-24T00:49:27.647Z
response_nonce: 0be8c14998c1a177528ab5d15275aab9
Docs Version 1

Row Grouping

ZingGrid has the ability to group rows. Enable this feature by adding the groupBy attribute to your grid and specifying which field(s) to group rows in.

Default Row Group Settings

Easily enable row grouping by setting the groupBy attribute on the <zing-grid> tag (see below). Specify a column index (or indices) to specify which fields to group by.

<zing-grid group-by="season,episode"></zing-grid>
Top

Row Group Type

The row group column type can either be used to reference an existing row group column or to add it.

To add a row group column with <zg-column>, set the column type to "row-group" and specify the columns with index.

To reference an existing row group column added by ZingGrid[groupBy], only set the type attribute to "row-group" on <zg-column>.

<zg-colgroup>
  <zg-column type="row-group" index="season,episode"></zg-column>
  ...
</zg-colgroup>
Top

Dynamically Grouping

If you intend to dynamically update which indices are included in row grouping, use the group attribute. Just add or remove the attribute from <zg-column>.

Note that if ZGColumn has the group attribute, all other attributes are ignored. The reasoning behind this is that the column is essentially hidden. Enable features by setting attributes on the [type="row-group"] column that references it.

<zg-colgroup>
  <zg-column type="row-group"></zg-column>
  <zg-column index="season" group></zg-column>
  <zg-column index="episode" group></zg-column>
  ...
</zg-colgroup>
Top

Sub-Group Headers

The head cell of a column in a grouped row can be set display an aggregate value by setting the [groupHeadCell] attribute on <zg-column>. Check out available methods in Aggregate Methods section.

Note that [groupHeadCell] accepts a custom function to display a value in the group head cell. The default arguments to the custom function are:

  • rowGroup - Row group information
  • groupCell - Data on rows within row group (use to calculate aggregate value)
  • record - info related to the row
<zg-colgroup>
  <zg-column index="first"></zg-column>
  <zg-column index="last"></zg-column>
  <zg-column index="score" group-head-cell="avg"></zg-column>
</zg-colgroup>
Top

Hide Count

To hide the row count in the row-group column, set the type-group-hide-count to "disabled".

<zg-colgroup>
  <zg-column type="row-group" type-group-hide-count="disabled"></zg-column>
  <zg-column index="season" group></zg-column>
  <zg-column index="episode" group></zg-column>
  ...
</zg-colgroup>
Top

Tokens

In order to customize the cell contents of the row-group column, use a renderer or template. Here is a list of group-related tokens to utilize:

  • name: group name
  • count: row count of the group
  • plural: word chosen depending on the row count

To set the value of the "plural" token, use type-group-plural. The attribute accepts a comma-separated string (ex. "single,plural").

<zg-colgroup>
  <zg-column type="row-group" index="season,episode" type-group-plural="person,people">
    [[group.name]] -- [[group.count]] [[group.plural]]
  </zg-column>
  ...
</zg-colgroup>
Top

External Input (get/set)

You can use an external input through the API method setGroupBy('...') (see below) to dynamically enable row grouping.

The getGroupBy() API method will return which indices have row grouping enabled.

const zgRef =document.querySelector('zing-grid');
zgRef.setGroupBy('season,episode');

console.log(zgRef.getGroupBy());   // 'season,episode'
Top

[features: row grouping]