GroupDataGrid Component

Basics

The following example groups customers based on their respective values in the Grade column.

groupdatagrid basic
XML code 
<data>
    <collection id="customersDc" class="com.company.groupdatagridex1.entity.Customer">
        <loader id="customersDl" readOnly="true">
            <query>
                <![CDATA[select e from Customer e]]>
            </query>
        </loader>
        <fetchPlan extends="_base"/>
    </collection>
</data>
    <groupg:groupDataGrid id="customersGroupDataGrid"
                          dataContainer="customersDc"
                          minWidth="100px"
                          width="100%">
        <groupg:groupBy>
            <groupg:columnRef key="grade"/> (1)
        </groupg:groupBy>
        <groupg:columns>
            <groupg:groupColumn header="Grade"/> (2)
            <groupg:column property="firstName"/>
            <groupg:column property="lastName"/>
            <groupg:column property="email"/>
            <groupg:column property="country"/>
            <groupg:column property="grade"/>
        </groupg:columns>
    </groupg:groupDataGrid>
1 Initial grouping is by the grade property; more groupings can be added.
2 Group column definition.

Data Binding

Data binding refers to linking a visual component to a data container. To bind a component to data use the dataContainer attribute and reference collection container. See the example above.

Group Item

Group items are special records produced by grouping. They appear as rows that contain nothing but a group header.

groupdatagrid group items

To render group items, the data-binding layer creates a temporary, empty entity or DTO instance. This instance is not added to the collection container and exists only in memory for the duration of the grouping.

Hide Group Item Count

By default, group items display the number of descendants. Use the displayItemCount property of groupColumn to hide this number.

groupdatagrid hide count

Multi-level Grouping

The component supports grouping by multiple columns. Click the grouping column icon to open the Group by dialog, then add or remove columns.

groupdatagrid multiple

Disable Grouping

To prevent users from grouping by a specific column, set its groupAllowed property to false. In the example below, the Country column cannot be grouped through the Group by dialog.

groupdatagrid groupallowed
XML code 
<groupg:groupDataGrid id="customersGroupDataGrid"
                      dataContainer="customersDc"
                      minWidth="100px"
                      width="100%">
    <groupg:groupBy>
        <groupg:columnRef key="grade"/>
    </groupg:groupBy>
    <groupg:columns>
        <groupg:groupColumn header="Grade"/>
        <groupg:column property="firstName"/>
        <groupg:column property="lastName"/>
        <groupg:column property="email"/>
        <groupg:column property="country" groupAllowed="false"/>
        <groupg:column property="grade"/>
    </groupg:columns>
</groupg:groupDataGrid>
Columns with groupAllowed = false may be used for default grouping through the groupBy element. They can also be grouped programmatically using the groupBy() method.

Custom Grouping Column

To use a custom grouping value, describe a new grouping property in the view controller. The following example introduces a new grouping property that combines first and last name.

groupdatagrid custom column
XML code 
<groupg:groupDataGrid id="customersGroupDataGrid"
                      dataContainer="customersDc"
                      minWidth="100px"
                      width="100%">
    <groupg:columns>
        <groupg:groupColumn key="group" header="Full name"/> <!-- 1 -->
        <groupg:column key="fullName" header="Full name"/>
        <groupg:column property="email"/>
        <groupg:column property="country"/>
        <groupg:column property="grade"/>
    </groupg:columns>
</groupg:groupDataGrid>
Java code 
@ViewComponent
private GroupDataGrid<Customer> customersGroupDataGrid;

@Subscribe
public void onInit(InitEvent event) {
    GroupDataGridItems<Customer> items = customersGroupDataGrid.getItems();

    if (items != null) {
        items.addGroupPropertyDescriptor( (1)
                new BaseGroupPropertyDescriptor<Customer>("fullName",
                        context -> context.getItem().getFirstName() + " " + context.getItem().getLastName())
                        .withSortProperties(List.of("firstName", "lastName")));

        customersGroupDataGrid.groupByKeys("fullName"); (2)
    }
}
@Supply(to = "customersGroupDataGrid.fullName", subject = "renderer") (3)
protected Renderer<Customer> supplyRendererToFullNameColumn() {
    return new TextRenderer<>(item -> item.getFirstName() + " " + item.getLastName());
}
1 Describe a new grouping property that concatenates firstName and lastName.
2 Group by fullName by default.
3 Provide a render fallback for the Full Name column when it is not grouped; without this the column will appear empty.

Export to Excel

Exporting functionality is provided by free Grid Export Actions add-on which supports all grid types: groupDataGrid, dataGrid, and treeDataGrid.

groupdatagrid export

The add-on provides two export options. For groupDataGrid it affects both the scope and the generated spreadsheet formating:

  • All rows – Exports every row from the grid and flattens grouping: group labels become regular cell values placed in the first column.

  • Current page – Exports only the rows visible on the current page and preserves the grouping structure in the generated XLS file. Group headers and indentation are maintained so the exported spreadsheet reflects the same hierarchical layout you see in the grid.

Styling

Themes

LIVE DEMO

Configure themes with the themeNames property. Multiple themes can be applied simultaneously. The themes are the same ones as in dataGrid.

Group Icon

The component shows + for a collapsed group and - for an expanded group. To customize, add your preferred icons to the application stylesheet. Replace the default content values for the desired icon character codes (e.g., e7c1 and e7bf taken from vaadin font icons collection):

application.css
vaadin-grid-tree-toggle.jmix-group-toggle {
    &::part(toggle)::before {
        content: "\e7c1";
    }

    &[expanded]::part(toggle)::before {
        content: "\e7bf";
    }
}
groupdatagrid groupicon
Learn more about stylable parts of components.

Group Column Icon

The group column icon is customizable via the groupIcon attribute of the groupColumn element. To hide the icon, set groupIconVisible to false.

Attributes

Common attributes serve the same purpose for all components. Below are the attributes shared with dataGrid and those unique to groupDataGrid:

Name

Description

Default

aggregatable

If true, enables aggregating of columns. See Aggregating.

false

columnReorderingAllowed

If true, enables users to change the order of columns.

false

emptyStateText

The text to display when the table is empty. Use null to remove the current empty state content. See Empty State.

–

selectionMode

Sets the selection mode. Possible values: SINGLE, MULTI.

SINGLE

aggregationPosition

If the data in the component is aggregatable, determines whether the aggregation row is displayed above or below the other rows. Possible values: TOP or BOTTOM. See Aggregating.

BOTTOM

allRowsVisible

If true, the data grid will display all rows at once with no scroll bars, effectively disabling virtual scrolling. This means that instead of only rendering the visible rows and loading more as the user scrolls, the grid will render all the rows in the DOM simultaneously.

Using this feature is discouraged for a large number of items as it may cause performance issues.

–

columnRendering

Sets the column rendering mode. In EAGER mode, all columns are rendered upfront, regardless of their visibility within the viewport. In LAZY mode, body cells rendered only when the corresponding columns are inside the visible viewport.

EAGER

detailsVisibleOnClick

If true, enables item details to be revealed on mouse click.

true

dropMode

Determines rows where a drop can happen. Possible values: BETWEEN, ON_TOP, ON_TOP_OR_BETWEEN, ON_GRID. This feature might be used, for example, to reorder rows and to drag rows between grids.

–

editorBuffered

If true, activates buffered mode for inline editing, meaning that the user must confirm making changes by clicking a confirm button. This mode also allows users to cancel their changes. In unbuffered mode changes are applied without the need for confirmation.

false

multiSort

If true, enables sorting by multiple columns.

false

multiSortOnShiftClickOnly

If true, multi-sorting is activated only when clicking on the column header while holding down the Shift key.

false

multiSortPriority

Determines whether the clicked column is added to the end or beginning of the sorted columns list. Possible values: PREPEND, APPEND.

PREPEND

nestedNullBehavior

Sets the behavior when parsing nested properties which may contain null values in the property chain. Possible values: THROW, ALLOW_NULLS.

THROW

pageSize

Determines the page size or the number of items that will be fetched from the data provider at a time.

50

rowsDraggable

If true, enables users to drag rows in the grid.

false

sortByGroupEnabled

If true, enables sorting by group.

true

Handlers

Common handlers are configured in the same way for all components. Below are the handlers shared with dataGrid and those unique to groupDataGrid:

To generate a handler stub in Jmix Studio, use the Handlers tab of the Jmix UI inspector panel or the Generate Handler action available in the top panel of the view class and through the Code → Generate menu (Alt+Insert / Cmd+N).

Name

Description

CellFocusEvent

com.vaadin.flow.component.grid.CellFocusEvent fired when a cell in the data grid is focused. Corresponds to the grid-cell-focus DOM event.

CollapseEvent

Fired when a group is collapsed.

ColumnReorderEvent

com.vaadin.flow.component.grid.ColumnReorderEvent fired when the columns in the data grid are reordered. Corresponds to the column-reorder-all-columns DOM event.

ColumnResizeEvent

com.vaadin.flow.component.grid.ColumnResizeEvent fired when a data grid column is resized by the user. Corresponds to the column-drag-resize DOM event.

ExpandEvent

Fired when a group is expanded.

GridDragEndEvent

com.vaadin.flow.component.grid.dnd.GridDragEndEvent - drag end event of dataGrid rows. Corresponds to the grid-dragend DOM event.

GridDragStartEvent

com.vaadin.flow.component.grid.dnd.GridDragStartEvent - drag start event of dataGrid rows. Corresponds to the grid-dragstart DOM event.

GridDragDropEvent

com.vaadin.flow.component.grid.dnd.GridDragDropEvent - drop event that occurs on the data grid or its rows. Corresponds to the grid-drop DOM event.

GroupDataGridGroupItemClickEvent

Fired when a row that corresponds to a group item is clicked

GroupDataGridGroupItemDoubleClickEvent

Fired when a row that corresponds to a group item is double-clicked.

GroupDataGridGroupingChangedEvent

Fired when grouping changes — columns added or removed.

ItemClickEvent

com.vaadin.flow.component.grid.ItemClickEvent fired when a data grid item is clicked. Corresponds to the item-click DOM event.

ItemDoubleClickEvent

com.vaadin.flow.component.grid.ItemDoubleClickEvent fired when a data grid item is double-clicked. Corresponds to the item-double-click DOM event.

SelectionEvent

A selection event that unifies the way to access to selection event for multi selection and single selection components (in case when only one selected item is required).

SortEvent

com.vaadin.flow.data.event.SortEvent - event describing a change in sorting of a DataProvider. Fired by SortNotifiers.

dataGenerator

Adds a data generator for the data grid. If the generator was already added, does nothing. See the com.vaadin.flow.data.provider.HasDataGenerators interface.

dragFilter

Allows to control which specific rows can be dragged, rather than making all rows draggable with rowsDraggable.

dropFilter

Allows to control which specific rows are valid drop targets.

enterPressHandler

Handles the event when the user presses the Enter key.

groupPartNameGenerator

Generates parts of CSS class names for group items based on given conditions. This allows for customizing group items.

itemSelectableProvider

Sets a predicate to check whether a specific item in the grid may be selected or deselected by the user. The predicate receives an item instance and should return true if a user may change the selection state of that item, or false otherwise.

partNameGenerator

Generates parts of CSS class names for cells based on given conditions. This allows for customizing cell appearance based on the data displayed.

tooltipGenerator

Generates tooltip for the column cell based on given conditions. See live demo.

Elements

To add an element to a selected component click the Add button in the Jmix UI inspector panel.

groupBy

The groupBy element contains one or more columnRef elements that reference the columns used for default grouping.

columns

The columns element contains individual column elements and defines a set of attributes shared by those columns.

column

The column element declares an individual column. Attributes set for an individual column override those set for columns.

groupColumn

The groupColumn element declares the column used for grouping and its relative position among other columns. The key attribute is required.