Blazor Grid Group By

    The Ignite UI for Blazor Group By behavior in Blazor IgbGrid creates grouped data rows based on the column values. The Group By in the IgbGrid allows for visualizing the groups in a hierarchical structure. The grouped data rows can be expanded or collapsed and the order of grouping may be changed through the UI or API. When Row Selection is enabled, a Group By row selector is rendered in the left-most area of the group row. In case the RowSelection property is set to single, checkboxes are disabled and only serve as an indication for the group where selection is placed. If the RowSelection property is set to multiple, clicking over the Group By row selector selects all records belonging to this group.

    Blazor Grid Group By Example

    This example presents the grouping capabilities of a large amount of data. Dragging the column headers to the top (grouping area) allows users to see the data for the selected column in a hierarchical structure. They can do group by in multiple fields by dragging more column headers to the top. These grouping options come in handy when you have tables with numerous rows and columns where users want to present the data in a much faster and visually acceptable way.

    Initial Grouping State

    It is possible to define initial grouping of the grid by assigning an array of expressions to the GroupingExpressions property of the grid.

    <IgbGrid AutoGenerate="true" Data="InvoicesData" @ref="grid" Id="grid" GroupingExpressions="GroupingExpression1"></IgbGrid>

@code {
    public IgbGroupingExpression[] GroupingExpression1 = new IgbGroupingExpression[2]
    {
        new IgbGroupingExpression(){ FieldName = "ShipCountry", Dir= SortingDirection.Asc },
        new IgbGroupingExpression() { FieldName = "ShipCity", Dir= SortingDirection.Asc  }
    };
}

    Grouping expressions implement the ISortingExpression interface.

    Group By API

    Grouping API

    Grouping is available through the UI and through a robust API exposed by the grid component. Developers can allow end-users to group the grid data by certain columns, by setting each column's Groupable property to true.

    <IgbGrid AutoGenerate="false" Data="InvoicesData" @ref="grid" Id="grid" GroupingExpressions="GroupingExpression1" GroupRowTemplateScript="WebGridGroupByRowTemplate">
    <IgbColumn Field="OrderID" Hidden="true"></IgbColumn>
    <IgbColumn Field="ShipCountry" Header="Ship Country" Width="200px" Groupable="true"></IgbColumn>
    <IgbColumn Field="OrderDate" Header="Order Date" DataType="GridColumnDataType.Date" Width="200px" Groupable="true"></IgbColumn>
    <IgbColumn Field="PostalCode" Header="Postal Code" Width="200px" Groupable="true"></IgbColumn>
    <IgbColumn Field="Discontinued" Width="200px" DataType="GridColumnDataType.Boolean" Groupable="true" BodyTemplateScript="WebGridBooleanCellTemplate" Name="column1" @ref="column1"></IgbColumn>
    <IgbColumn Field="ShipName" Header="Ship Name" Width="200px" Groupable="true"></IgbColumn>
    <IgbColumn Field="ShipCity" Header="Ship City" Width="200px" Groupable="true"></IgbColumn>
    <IgbColumn Field="ShipperName" Header="Shipper Name"Width="200px"Groupable="true"></IgbColumn>
    <IgbColumn Field="Salesperson" Header="Sales Person" Width="200px" Groupable="true"></IgbColumn>
    <IgbColumn Field="UnitPrice" Header="Unit Price" Width="200px" Groupable="true"></IgbColumn>
    <IgbColumn Field="Quantity" Width="200px" Groupable="true"></IgbColumn>
</IgbGrid>

    During runtime the expressions are gettable and settable from the groupingExpressions property. If you need to add or change an existing expression you may also use the GroupBy method with either a single or an array of expressions.

    @code {
    public IgbGrid grid;

    public IgbGroupingExpression[] GroupingExpression1 = new IgbGroupingExpression[2]
    {
        new IgbGroupingExpression(){ FieldName = "ShipCountry", Dir= SortingDirection.Asc },
        new IgbGroupingExpression() { FieldName = "ShipCity", Dir= SortingDirection.Asc  }
    };


    private void GroupGrid()
    {
        this.grid.GroupBy(GroupingExpression1);
    }
}

    Expand/Collapse API

    In addition to grouping expressions you can also control the expansion states for group rows. They are stored in a separate property of the IgbGrid component GroupingExpansionState which is a collection of IgbGroupByExpandState. Each expansion state is uniquely defined by the field name it is created for and the value it represents for each level of grouping, i.e. the identifier is a hierarchy array of IgbGroupByKey.

    As with GroupingExpressions, setting a list of IgbGroupByExpandState directly to the GroupingExpansionState will change the expansion accordingly. Additionally IgbGrid exposes a method toggleGroup that toggles a group by the group record instance or via the expanded property of the row.

    <IgbGrid AutoGenerate="true" Data="InvoicesData" GroupingExpressions="GroupingExpression1" GroupingExpansionState=ExpansionState @ref="grid" Id="grid">
</IgbGrid>

@code {
    public IgbGroupingExpression[] GroupingExpression1 = new IgbGroupingExpression[2]
    {
        new IgbGroupingExpression(){ FieldName = "ShipCountry", Dir= SortingDirection.Asc },
        new IgbGroupingExpression() { FieldName = "ShipCity", Dir= SortingDirection.Asc  }
    };
    public IgbGroupByExpandState[] state = new IgbGroupByExpandState[1]
    {
        new IgbGroupByExpandState(){ Hierarchy = new IgbGroupByKey[1]{ new IgbGroupByKey() { FieldName="ShipCountry", Value = "USA" } },  Expanded = false }
    };
}

    Groups can be created expanded (default) or collapsed and the expansion states would generally only contain the state opposite to the default behavior. You can control whether groups should be created expanded or not through the GroupsExpanded property.

    Select/Deselect All Rows in a Group API

    Selecting/Deselecting all rows in a group is available through the SelectRowsInGroup and DeselectRowsInGroup API methods.

    The code snippet below can be used to select all rows within a group using the group record instance SelectRowsInGroup method. Additionally, the second parameter of this method is a boolean property through which you may choose whether the previous row selection will be cleared or not. The previous selection is preserved by default.

    var row = await this.grid.GetRowByIndexAsync(0);
this.grid.SelectRowsInGroup(row.GroupRow, true);

    If you need to deselect all rows within a group programmatically, you can use the DeselectRowsInGroup method.

    var row = await this.grid.GetRowByIndexAsync(0);
this.grid.DeselectRowsInGroup(row.GroupRow);

    Templating

    Group Row Templates

    The group row except for the expand/collapse UI is fully templatable. By default it renders a grouping icon and displays the field name and value it represents. The context to render the template against is of type IgbGroupByRecord.

    As an example, the following template would make the group rows summary more verbose:

    <IgbGrid AutoGenerate="true" Data="InvoicesData" @ref="grid" Id="grid" GroupRowTemplateScript="WebGridGroupByRowTemplate"></IgbGrid>


//In JavaScript:
igRegisterScript("WebGridGroupByRowTemplate", (ctx) => {
    var html = window.igTemplating.html;
    var groupRow = ctx.implicit;
    return html`<span>Total items with value: ${groupRow.value} are ${groupRow.records.length}</span>`;
}, false);

    Group Row Selector Templates

    As mentioned above the group row except for the expand/collapse UI is fully templatable. To create a custom Group By row selector template use GroupByRowSelectorTemplate. From the template, you can access the implicitly provided context variable, with properties that give you information about the Group By row's state.

    The SelectedCount property shows how many of the group records are currently selected while TotalCount shows how many records belong to the group.

    <IgbGrid GroupByRowSelectorTemplateScript="GroupByRowSelectorTemplate"></IgbGrid>
//In Javascript
igRegisterScript("GroupByRowSelectorTemplate", (ctx) => {
    var html = window.igTemplating.html;
    return html` ${ctx.implicit.selectedCount} / ${ctx.implicit.totalCount} `;
}, false);

    The GroupRow property returns a reference to the group row.

    <IgbGrid GroupByRowSelectorTemplateScript="GroupByRowSelectorTemplate"></IgbGrid>
//In Javascript
igRegisterScript("GroupByRowSelectorTemplate", (ctx) => {
    var html = window.igTemplating.html;
    var groupRow = ctx.implicit.groupRow;
    return html`<div onclick="handleGroupByRowSelectorClick()">Handle groupRow</div> `;
}, false);

    The SelectedCount and TotalCount properties can be used to determine if the Group By row selector should be checked or indeterminate (partially selected).

    Blazor Grid Group By With Paging

    Group rows participate in the paging process along with data rows. They count towards the page size for each page. Collapsed rows are not included in the paging process. Any expand or collapse operation forces Paging to recalculate the page count and adjust the page index if necessary. Groups that span multiple pages are split between them. The group row is visible only on the page it starts on and is not repeated on subsequent pages. Summary information for group rows is calculated based on the whole group and is unaffected by Paging.

    Blazor Group By With Paging Example

    Group By With Summaries

    Integration between Group By and Summaries is described in the Summaries topic.

    Keyboard Navigation

    The grouping UI supports the following keyboard interactions:

    • For group rows (focus should be on the row or the expand/collapse cell)

      • ALT + RIGHT - Expands the group
      • ALT + LEFT - Collapses the group
      • SPACE - selects all rows in the group, if rowSelection property is set to multiple

    • For group IgbChip components in the group by area (focus should be on the chip)

      • SHIFT + LEFT - moves the focused chip left, changing the grouping order, if possible
      • SHIFT + RIGHT - moves the focused chip right, changing the grouping order, if possible
      • SPACE - changes the sorting direction
      • DELETE - ungroups the field
      • The separate elements of the chip are also focusable and can be interacted with using the ENTER key.

    Styling

    In addition to the predefined themes, the grid could be further customized by setting some of the available CSS properties. In case you would like to change some of the colors, you need to set a class for the grid first:

    <IgbGrid Class="grid"></IgbGrid>

    Then set the related CSS properties for that class:

    .grid {
    --ig-grid-group-row-background: #969799;
    --ig-grid-group-row-selected-background: #969799;
    --ig-grid-group-label-column-name-text: #f8f8f8;
    --ig-grid-group-label-text: #f8f8f8;
    --ig-grid-group-count-text-color: #222;
    --ig-grid-expand-icon-color: #f8f8f8;
    --ig-grid-expand-icon-hover-color: #f8f8f8;
}

    Demo

    Known Limitations

    Limitation Description
    Maximum amount of grouped columns is 10. If more than 10 columns are grouped an error is thrown.

    API References

    Additional Resources

    Our community is active and always welcoming to new ideas.