groupDataGrid

This component requires the commercial Grouping Data Grid add-on.
LIVE DEMO

The groupDataGrid component is a more capable version of the base data grid with powerful features for grouping rows. It can group rows by repeated column values into collapsible group blocks with support for multi-level grouping and drag-to-reorder controls.

XML Element

groupDataGrid

Java Class

GroupDataGrid

Basics

Declare the groupg namespace in the view’s XML descriptor:

<view xmlns="http://jmix.io/schema/flowui/view"
      xmlns:groupg="http://jmix.io/schema/groupgrid/ui">

Studio adds the namespace automatically when you add the component using the Add Component action in the top actions panel. See Component Palette.

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

groupdatagrid basic
XML code 
<view xmlns="http://jmix.io/schema/flowui/view" xmlns:groupg="http://jmix.io/schema/groupgrid/ui"
      title="msg://basicGroupGridView.title"> (1)
    <data>
        <collection id="customersDc"
                    class="com.company.groupdatagridex1.entity.Customer"
                    fetchPlan="_base">
            <loader id="customersDl">
                <query>
                    <![CDATA[select e from Customer e]]>
                </query>
            </loader>
        </collection>
    </data>
    <facets>
        <dataLoadCoordinator auto="true"/>
    </facets>
    <layout>
        <groupg:groupDataGrid id="customersGroupDataGrid"
                              dataContainer="customersDc"
                              minWidth="100px"
                              width="100%">
            <groupg:groupBy>
                <groupg:columnRef key="grade"/> (2)
            </groupg:groupBy>
            <groupg:columns>
                <groupg:groupColumn header="Grade"/> (3)
                <groupg:column property="firstName"/>
                <groupg:column property="lastName"/>
                <groupg:column property="email"/>
                <groupg:column property="country"/>
                <groupg:column property="grade"/>
            </groupg:columns>
        </groupg:groupDataGrid>
    </layout>
</view>
1 The view declares the groupg namespace used by the component.
2 Initial grouping is by the grade property; more groupings can be added.
3 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 displayItemsCount 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

Sorting

Sorting configuration is the same as in dataGrid. The sortByGroupEnabled attribute defines whether sorting affects group order.

Disable Grouping

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

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>

To turn off grouping entirely for users, set displayColumnsGrouperOnIconClick="false" on the groupColumn element.

Default grouping can still be declared with the groupBy element or applied programmatically via 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.

Such a synthetic property is not sortable automatically. To make sorting work, specify sort properties in the group property descriptor using .withSortProperties(…​).

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"))); (2)

        customersGroupDataGrid.groupByKeys("fullName"); (3)
    }
}
@Supply(to = "customersGroupDataGrid.fullName", subject = "renderer") (4)
protected Renderer<Customer> supplyRendererToFullNameColumn() {
    return new TextRenderer<>(item -> item.getFirstName() + " " + item.getLastName());
}
1 Describe a new grouping property that concatenates firstName and lastName.
2 .withSortProperties(List.of("firstName", "lastName")) tells the component how to sort the synthetic property.
3 Group by fullName by default.
4 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 three export options. It affects both the scope and the generated spreadsheet formatting:

  • All Rows – Exports all rows and flattens the grouping.

  • Current Page – Exports only the visible rows while preserving the grouping structure as seen in the grid.

  • Selected Rows – Exports the currently selected rows and flattens the grouping.

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

The following attributes are specific 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.

false

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:

  • sorting is enabled for the group column.

  • sorting by other columns rearranges rows within each group but initial group order remains fixed.

If false:

  • sorting is disabled for the group column.

  • sorting by other columns reorders the groups accordingly.

true

The following shared attributes are supported by groupDataGrid:

id - alignSelf - ariaLabel - classNames - colspan - css - dataContainer - enabled - focusShortcut - height - justifySelf - maxHeight - maxWidth - metaClass - minHeight - minWidth - tabIndex - themeNames - visible - width

Handlers

The following handlers are specific 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.

GridDropEvent

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

GroupItemClickEvent

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

GroupItemDoubleClickEvent

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

GroupingChangedEvent

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.

groupTooltipGenerator

Generates tooltip for the group based on given conditions.

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.

sortBuilderDelegate

Builds a DataGridSort object from GroupDataGridSortContext, allowing component-specific mapping of columns to custom comparators and database sort expressions. See Sort Builder Delegate.

tooltipGenerator

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

The following shared handlers are supported by groupDataGrid:

AttachEvent - BlurEvent - DetachEvent - FocusEvent

Elements

A groupDataGrid can include actions, groupBy, columns, contextMenu, and emptyStateComponent as its direct nested elements. The columns element can contain column, groupColumn, and editorActionsColumn. The shared grid elements work as described for actions, contextMenu, and emptyStateComponent.

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 specifying which columns to group by.

columnRef

The columnRef element identifies a column to use for grouping. Its required key attribute must match the key of a declared column.

columns

The columns element contains individual column elements and defines a set of attributes shared by those columns. It supports includeAll, exclude, sortable, resizable, and filterable as described for dataGrid columns.

column

The column element declares an individual column. Attributes set for an individual column override those set for columns. It supports the dataGrid column configuration and adds the groupAllowed attribute, which controls whether users can group by that column. See Disable Grouping.

groupColumn

The groupColumn element declares the column used for grouping and its relative position among other columns. It can include a nested groupIcon element to provide a custom icon component.

Name Description Default

autoHidden

Sets whether the group column is hidden automatically when there are no grouped properties.

—

autoWidth

Sets whether the column width is calculated from its content.

—

displayColumnsGrouperOnIconClick

Sets whether clicking the group icon opens the Group by dialog.

—

displayItemsCount

Sets whether a group header displays the number of descendant items. See Hide Group Item Count.

—

flexGrow

Sets how the column grows relative to other columns.

—

footer

Sets the column footer text.

—

frozen

Freezes the column at the start edge of the grid.

—

frozenToEnd

Freezes the column at the end edge of the grid.

—

groupIcon

Sets the group icon using a Vaadin icon name. A nested groupIcon element takes precedence when a component icon is required.

—

groupIconVisible

Sets whether the group icon is visible.

—

header

Sets the column header text.

—

key

Sets the column key used to identify the group column.

—

resizable

Sets whether users can resize the column.

—

sortable

Sets whether users can sort by the group column.

—

visible

Sets whether the column is visible.

—

width

Sets the column width as a CSS length.

—