Grouping columns allows you to have multiple levels of columns in your header and the ability, if you want, to 'open and close' column groups to show and hide additional columns.
Grouping columns is done by providing the columns in a tree hierarchy to the grid. There is no limit to the number of levels you can provide.
Here is a code snippet of providing two groups of columns.
Column Definitions vs Column Group Definitions
The list of columns in
gridOptions.columnDefs can be a mix of columns and column groups.
You can mix and match at will, every level can have any number of columns and groups and in any
order. What you need to understand when defining as follows:
- The 'children' attribute is mandatory for groups and not applicable for columns.
- If a definition has a 'children' attribute, it is treated as a group. If it does not have a 'children' attribute, it is treated as a column.
- Most other attributes are not common across groups and columns (eg 'groupId' is only used for groups). If you provide attributes that are not applicable (eg you give a column a 'groupId') they will be ignored.
Showing / Hiding Columns
A group can have children initially hidden. If you want to show or hide children,
columnGroupShow to either 'open' or 'closed' to one or more of the children.
When a children set has
columnGroupShow set, it behaves in the following way:
- open: The child is only shown when the group is open.
- closed: The child is only shown when the group is closed.
- everything else: Any other value, including null and undefined, the child is always shown.
If a group has any child that is dependent on the open / closed state, the open / close icon will appear. Otherwise the icon will not be shown.
Having columns only show when closed is useful when you want to replace a column with others. For example, in the code snippet above (and the example below), the 'Total' columns is replaced with other columns when the group is opened.
If a group has an 'incompatible' set of children, then the group opening / closing will not be activated. An incompatible set is one which will have no columns visible at some point (ie all are set to 'open' or 'closed').
Pinning and Groups
Pinned columns break groups. So if you have a group with 10 columns, 4 of which are inside the pinned area, two groups will be created, one with 4 (pinned) and one with 6 (not pinned).
Moving Columns and Groups
If you move columns so that columns in a group are no longer adjacent, then the group will again be broken and displayed as one or more groups in the grid.
If you grab the group resize bar, it resizes each child in the group evenly distributing the new additional width. If you grab the child resize bar, only that one column will be resized.
The grid doesn't color the groups for you. However you can use the column definition
headerClass for this purpose. The
headerClass attribute is available
on both columns and column groups.
Here is a basic example of grouping in action.
Sometimes you want columns of the group to always stick together. To achieve this,
set the column group property
marryChildren=true. The example below
demonstrates the following:
Both 'Athlete Details' and 'Sports Results' have
- If you move columns inside these groups, you will not be able to move the column out of the group. For example, if you drag 'Athlete', it is not possible to drag it out of the 'Athlete Details' group.
- If you move a non group column, eg 'Extra 3', it will not be possible to place it in the middle of a group and hence impossible to break the group apart.
- It is possible to place a column between groups (eg you can place 'Extra 3' between the 'Athlete Details' and 'Sports Results').
Advanced Grouping Example
And here, to hammer in the 'no limit to the number of levels or groups', we have a more complex example. The grid here doesn't make much sense, it's just using the same Olympic Winners data and going crazy with the column groups. The example also demonstrates the following features:
- Using the API to open and close groups. To do this, you will need to provide your groups with an ID during the definition, or look up the groups ID via the API (as an ID is generated if you don't provide one).
colDef.openByDefaultproperty, where it sets this on F and G groups, resulting in these groups appearing as open by default.
defaultColDefto apply a class to some of the headers. Using this technique, you can apply style to any of the header sections.