Grouping rows
You can use any
field available in the DataSource to do the grouping - it can even be a field that is not a column.When using TypeScript, the types of the props are generic and take a
DATA_TYPE parameter - for example DataSourcePropGroupBy<DATA_TYPE> for the groupBy prop. The fields in that DATA_TYPE can then be used for grouping.In the example above, we're grouping by
country, which is a field available in the Person type. Specifying a field not defined in the Person type would be a type error.Additionally, a
column object can be used together with the field to define how the group column should be rendered.The example below puts it all together.
Also see the groupBy API reference to find out more.
#
Simple row grouping
loading demo…
In
groupBy.column you can use any column property - so, for example, you can define a custom renderValue function to customize the rendering.The generated group column(s) - can be one for all groups or one for each group - will inherit the
style/className/renderers from the columns corresponding to the group fields themselves (if those columns exist).Additionally, there are other ways to override those inherited configurations, in order to configure the group columns:
- use
groupBy.columnto specify how each grouping column should look for the respective field (in case ofgroupRenderStrateg="multi-column") - use
groupColumnprop- can be used as an object - ideal for when you have simple requirements and when
groupRenderStrateg="single-column" - as a function that returns a column configuration - can be used like this in either single or multiple group render strategy
- can be used as an object - ideal for when you have simple requirements and when
Controlling the collapse/expand state#
When you do grouping, by default, all row groups are expanded. Of course you have full control over this and you do this via the
groupRowsState/defaultGroupRowsState props.If you simply want to specify the initial expanded/collapsed state, you should use the
defaultGroupRowsState prop.const defaultGroupRowsState: DataSourcePropGroupRowsStateObject = {
collapsedRows: true,
expandedRows: [['Mexico'], ['Mexico', 'backend'], ['India']],
};The two properties in this object are
collapsedRows and expandedRows, and each can have the following values:true- meaning that all groups have this state- an array of arrays - representing the exceptions to the default value
So if you have
collapsedRows set to true and then expandedRows set to [['Mexico'], ['Mexico', 'backend'], ['India']] then all rows are collapsed by default, except the rows specified in the expandedRows.#
Everything is collapsed except a few rows
loading demo…
You can specify expand/collapse state at any level of nesting.
Let's suppose by default all rows are collapsed - if you want a node to be visible then you have to specify all its parents as expanded.
So having this
will show all rows as collapsed, and just as soon as you expand
Mexico you will see the backend group row for Mexico to be expanded.This data format gives you ultimate flexibility and allows you to easily restore an expand/collpase state at a later time, if you wanted to.
If you use the controlled
groupRowsState, make sure you update it by leveraging the onGroupRowsStateChange callback prop.#
Using controlled expanded/collapsed state for group rows
loading demo…
In addition to simple objects with the shape described above, the
groupRowsState/defaultGroupRowsState can also be instanges of GroupRowsState class, which is exported by the Infinite Table package. This class is simply a wrapper around those objects, but it gives you additional utility methods.The
onGroupRowsStateChange callback gives you an instance of GroupRowsState back as the single argument. If you're using plain objects, just do groupRowsState.getState() and you'll get the corresponding plain object for the current expand/collapse state.GroupRowsState give you some additional helper methods, which you can read about hereKeep a
GroupRowsState instance in a shallowRef, as the example above does. A ref unwraps the type of the class instance, so its value no longer type-checks as a GroupRowsState.Grouping strategies#
Multiple grouping strategies are supported by,
InfiniteTable DataGrid:- multi column mode - multiple group columns are generated, one for each specified group field
- single column mode - a single group column is generated, even when there are multiple group fields
You can specify the rendering strategy explicitly by setting the
groupRenderStrategy property to any of the following: multi-column, single-column. If you don't set it explicitly, it will choose the best default based on your configuration.Multiple groups columns#
When grouping by multiple fields, by default the component will render a group column for each group field
Let's see an example of how the component would render the table with the multi-column strategy.
#
Multi-column group render strategy
loading demo…
For the
multi-column strategy, you can use hideEmptyGroupColumns in order to hide columns for groups which are currently not visible.#
Hide Empty Group Columns
loading demo…
You can specify an
id for group columns. This is helpful if you want to size those columns (via columnSizing) or pin them (via columnPinning) or configure them in other ways. If no id is specified, it will be generated like this: "group-by-${field}"Single group column#
You can group by multiple fields, yet only render a single group column. To choose this rendering strategy, specify
groupRenderStrategy property to be single-column (or specify groupColumn as an object.)In this case, you can't override the group column for each group field, as there's only one group column being generated. However, you can specify a
groupColumn property to customize the generated column.By default the generated group column will "inherit" many of the properties (the column style or className or renderers) of the columns corresponding to the group fields (if such columns exist, because it's not mandatory that they are defined).
#
Single-column group render strategy
loading demo…
If
groupColumn is specified to an object and no groupRenderStrategy is passed, the render strategy will be single-column.groupColumn can also be a function, which allows you to individually customize each group column - in case the multi-column strategy is used.You can specify an
id for the single groupColumn. This is helpful if you want to size this column (via columnSizing) or pin it (via columnPinning) or configure it in other ways. If no id is specified, it will default to "group-by".Customizing the group column#
There are many ways to customize the group column(s) and we're going to show a few of them below:
Binding the group column to a field
By default, group columns only show values in the group rows - but they are normal columns, so why not bind them to a field of the
DATA_TYPE?This makes the column display the value of the
field in non-group/normal rows, and in nested group rows when using multi-column grouping. Pivoted grids only render group rows, so that nested-row path is how a bound field still shows — indented one extra nesting level, like a leaf. With groupRenderStrategy set to single-column, the deepest (leaf) group rows in a pivot get that same extra indent. The field does not have to be a grouping key: nested rows show it when every item in the group has the same value (aggregators still win when the field is aggregated). Also, if you have another column bound to that field, the renderers/styling of that column will be used for the value of the group column, in those rows.#
Bind group column to a field
loading demo…
Use groupColumn to customize rendering
The
groupColumn will inherit its own rendering and styling from the columns that are bound to the fields used in groupBy.field. However, you can override any of those properties so you have full control over the rendering process.#
Customize group column renderer
The column that renders the
firstName has a custom renderer that adds a . at the end.
The group column is bound to the same firstName field, but specifies a different renderer, which will be used instead.loading demo…
Column rendering
Learn more about customizing column rendering via multiple renderer functions.
Hiding columns when grouping#
When grouping is enabled, you can choose to hide some columns. Here are the two main ways to do this:
- use
hideColumnWhenGrouped- this will make columns bound to the group fields be hidden when grouping is active - use
columns.defaultHiddenWhenGroupedBy(also available on the column types, ascolumnTypes.defaultHiddenWhenGroupedBy) - this is a column-level property, so you have more fine-grained control over what is hidden and when.
Valid values for
columns.defaultHiddenWhenGroupedBy are:"*"- when any grouping is active, hide the column that specifies this propertytrue- when the field this column is bound to is used in grouping, hides this columnkeyof DATA_TYPE- specify an exact field that, when grouped by, makes this column be hidden{[k in keyof DATA_TYPE]: true}- an object that can specify more fields. When there is grouping by any of those fields, the current column gets hidden.
#
Hide columns when grouping
In this example, the column bound to
firstName field is set to hide when any grouping is active, since the group column is anyways found to the firstName field.In addition,
hideColumnWhenGrouped is set to true, so the stack and preferredLanguage columns are also hidden, since they are grouped by.loading demo…
Sorting the group column#
When
groupRenderStrategy="single-column" is used, the group column is sortable by default if all the columns that are involved in grouping are sortable. Sorting the group column makes the sortInfo have a value that looks like this:To start with that sort,
{ id: 'group-by', dir: 1 } is enough — field is filled in from groupBy, and the sort type is taken from the columns bound to those fields.groupRenderStrategy="multi-column", each group column is sortable by default if the column with the corresponding field is sortable.The
columnDefaultSortable property can be used to override the default behavior.#
Group column with initial descending sorting
loading demo…
When a group column is configured and the
groupBy fields are not bound to actual columns in the table, the group column will not be sortable by default.If you want to make it sortable, you have to specify a
columns.sortType array, of the same length as the groupBy array, that specifies the sort type for each group field.Aggregations#
When grouping, you can also aggregate the values of the grouped rows. This is done via the
DataSource.aggregationReducers property. See the example below#
Grouping with aggregations
loading demo…
Each reducer from the
aggregationReducers map can have the following properties:field- the field to aggregate ongetter(data)- a value-getter function, if the aggregation values are are not mapped directly to afieldinitialValue- the initial value to start with when computing the aggregation (for client-side aggregations only)reducer: string | (acc, current, data: DATA_TYPE, index)=>value- the reducer function to use when computing the aggregation (for client-side aggregations only). For server-side aggregations, this will be astringdone(value, arr)- a function that is called when the aggregation is done (for client-side aggregations only) and returns the final value of the aggregationname- useful especially in combination withpivotBy, as it will be used as the pivot column header.
If an aggregation reducer is bound to a
field in the dataset, and there is a column mapped to the same field, that column will show the corresponding aggregation value for each group row, as shown in the example above.If you want to prevent the user to expand the last level of group rows, you can override the
render function for the group column#
Customized group expand on last group level
loading demo…
Aggregations
Dive deeper into the aggregation reducers and how they work.
Server side grouping with lazy loading#
Lazy loading becomes all the more useful when working with grouped data.
The
DataSource data function is called with an object that has all the information about the current DataSource state(grouping/pivoting/sorting/lazy-loading, etc) - see the paragraphs above for details.Server side grouping needs two kinds of data responses in order to work properly:
- response for non-leaf row groups - these are groups that have children. For such groups (including the top-level group), the
DataSource.datafunction must return a promise that's resolved to an object with the following properties:totalCount- the total number of records in the groupdata- an array of objects that describes non-leaf child groups, each object has the following properties:keys- an array of the group keys (usually strings) that uniquely identifies the group, from the root to the current groupdata- an object that describes the common properties of the groupaggregations- an object that describes the aggregations for the current grouptotalChildrenCount- optional - the number of leaf rows in the group, at any depth. Multiple row selection uses it to render the checkbox of a group whose rows are not loaded.totalChildrenCountUnfiltered- optional - the same count, without the filter. See lazy selection with a filter.
totalChildrenCount- optional, for the top-level group - the number of all leaf rows. Multiple row selection uses it for the header checkbox.totalChildrenCountUnfiltered- optional, for the top-level group - the number of all leaf rows, without the filter
- response for leaf rows - these are normal rows - rows that would have been served in the non-grouped response. The resolved object should have the following properties:
data- an array of objects that describes the rowstotalCount- the total number of records on the server, that are part of the current group
Here's an example, that assumes grouping by
country and city and aggregations by age and salary (average values):Now let's expand the first group and see how the request/response would look like:
Finally, let's have a look at the leaf/normal rows and a request for them:
When a row group is expanded, since
InfiniteTable has the group keys from the previous response when the node was loaded, it will use the keys array and pass them to the DataSource.data function when requesting for the children of the respective group.You know when to serve last-level rows, because in that case, the length of the
groupKeys array will be equal to the length of the groupBy array.#
Server side grouping with lazy loding
loading demo…
Eager loading for group row nodes#
When using lazy-loading together with batching, node data (without children) is loaded when a node (normal or grouped) comes into view. Only when a group node is expanded will its children be loaded. However, you can do this loading eagerly, by using the
dataset property on the node you want to load.This can be useful in combination with using
dataParams.groupRowsState from the data function - so your datasource can know which groups are expanded, and thus it can serve those groups already loaded with children.