The Ignite UI for Web Components Row Selection feature in Web Components Tree Grid allows users to interactively select, highlight, or deselect a single or multiple rows of data. There are several selection modes available in the IgcTreeGridComponent:
None Selection
Multiple Selection
Single Selection
Web Components Row Selection Example
The sample below demonstrates the four types of IgcTreeGridComponent's row selection behavior. Use the buttons below to enable each of the available selection modes. A brief description will be provided on each button interaction through a snackbar message box. Use the switch button to hide or show the row selector checkbox.
<!DOCTYPE html><html><head><title>Sample | Ignite UI | Web Components | infragistics</title><metacharset="UTF-8" /><linkrel="shortcut icon"href="https://static.infragistics.com/xplatform/images/browsers/wc.png" ><linkrel="stylesheet"href="https://fonts.googleapis.com/icon?family=Material+Icons" /><linkrel="stylesheet"href="https://fonts.googleapis.com/css?family=Kanit&display=swap" /><linkrel="stylesheet"href="https://fonts.googleapis.com/css?family=Titillium Web" /><linkrel="stylesheet"href="https://static.infragistics.com/xplatform/css/samples/shared.v8.css" /><linkrel="stylesheet"href="/src/index.css"type="text/css" /></head><body><divid="root"><divclass="container sample ig-typography"><divclass="options vertical"><igc-property-editor-paneldescription-type="WebTreeGrid"is-wrapping-enabled="true"is-horizontal="true"name="propertyEditorPanel1"id="propertyEditorPanel1"><igc-property-editor-property-descriptionname="selectionType"id="selectionType"property-path="RowSelection"label="Row Selection"></igc-property-editor-property-description><igc-property-editor-property-descriptionname="hideRowSelectors"id="hideRowSelectors"property-path="HideRowSelectors"label="Hide Row Selectors"></igc-property-editor-property-description></igc-property-editor-panel></div><divclass="container fill"><igc-tree-gridauto-generate="false"name="treeGrid"id="treeGrid"id="treeGrid"primary-key="ID"foreign-key="ParentID"cell-selection="none"allow-filtering="true"hide-row-selectors="false"><igc-columnfield="Name"data-type="string"sortable="true"></igc-column><igc-columnfield="Title"header="Job Title"data-type="string"sortable="true"></igc-column><igc-columnfield="HireDate"data-type="date"sortable="true"></igc-column><igc-columnfield="ID"data-type="number"sortable="true"></igc-column><igc-columnfield="Age"data-type="number"sortable="true"></igc-column><igc-columnfield="OnPTO"data-type="boolean"sortable="true"></igc-column></igc-tree-grid></div></div></div><!-- This script is needed only for parcel and it will be excluded for webpack -->
<% if (false) { %><scriptsrc="src/index.ts"></script><% } %>
</body></html>html
/* shared styles are loaded from: *//* https://static.infragistics.com/xplatform/css/samples */css
Like this sample? Get access to our complete Ignite UI for Web Components toolkit and start building your own apps in minutes. Download it for free.
Setup
In order to setup row selection in the IgcTreeGridComponent, you just need to set the rowSelection property. This property accepts GridSelectionMode enumeration.
GridSelectionMode exposes the following modes:
None
Single
Multiple
MultipleCascade
Below we will take a look at each of them in more detail.
None Selection
In the IgcTreeGridComponent by default row selection is disabled (rowSelection is None). So you can not select or deselect a row through interaction with the IgcTreeGridComponent UI, the only way to complete these actions is to use the provided API methods.
Single Selection
Single row selection can now be easily set up, the only thing you need to do, is to set rowSelection to Single property. This gives you the opportunity to select only one row within a grid. You can select a row by clicking on a cell or pressing the space key when you focus on a cell of the row, and of course you can select a row by clicking on the row selector field. When row is selected or deselected RowSelectionChanging event is emitted.
To enable multiple row selection in the IgcTreeGridComponent just set the rowSelection property to Multiple. This will enable a row selector field on each row and in the IgcTreeGridComponent header. The row selector allows users to select multiple rows, with the selection persisting through scrolling, paging, and data operations, such as sorting and filtering. The row also can be selected by clicking on a cell or by pressing the space key when a cell is focused. If you have selected one row and click on another while holding the shift key, this will select the whole range of rows. In this selection mode, when you click on a single row, the previous selected rows will be deselected. If you click while holding the ctrl key, the row will be toggled and the previous selection will be preserved.
To enable cascade row selection in the IgcTreeGridComponent just set the rowSelection property to MultipleCascade. This will enable a row selector field on each row and in the IgcTreeGridComponent header. The row selector allows users to select multiple rows which would select all children in the tree below. The selection persists through scrolling, paging, and data operations, such as sorting and filtering. The row can also be selected by clicking on a cell or by pressing the space key when a cell is focused. If you have selected one row and click on another while holding the shift key, the selection of a parent record will select all of its children even if they are not in the selected range. In this selection mode, when you click on a single row, the previously selected rows will be deselected. If you click while holding the ctrl key, the row and its children will be toggled and the previous selection will be preserved.
In this mode a parent's selection state entirely depends on the selection state of its children. When a parent has some selected and some deselected children, its checkbox is in an indeterminate state.
Notes
Row selection will trigger RowSelectionChanging event. This event gives you information about the new selection, old selection, the rows that have been added and removed from the old selection. Also the event is cancellable, so this allows you to prevent selection.
When row selection is enabled row selectors are displayed, but if you don't want to show them, you can set hideRowSelectors to true.
When you switch between row selection modes at runtime, this will clear the previous row selection state.
API usage
Select Rows Programmatically
The code snippet below can be used to select one or multiple rows simultaneously (via primaryKey). 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.
<igc-tree-gridid="grid"primary-key="ProductID"row-selection="Multiple"auto-generate="true"></igc-tree-grid><buttonid='select'>Select 1,2 and 5</button>html
When there is some change in the row selection RowSelectionChanging event is emitted. RowSelectionChanging exposes the following arguments:
OldSelection - array of row IDs that contains the previous state of the row selection.
NewSelection - array of row IDs that match the new state of the row selection.
Added - array of row IDs that are currently added to the selection.
Removed - array of row IDs that are currently removed according old selection state.
Event - the original event that triggered row selection change.
Cancel - allows you the prevent the row selection change.
<igc-tree-gridid="grid"></igc-tree-grid>html
constructor() {
const grid = document.getElementById('grid') as IgcTreeGridComponent;
grid.data = this.data;
grid.addEventListener("rowSelectionChanging", this.handleRowSelectionChange);
}
publichandleRowSelectionChange(args) {
args.detail.cancel = true; // this will cancel the row selection
}
ts
Select All Rows
Another useful API method that IgcTreeGridComponent provides is selectAllRows. By default this method will select all data rows, but if filtering is applied, it will select only the rows that match the filter criteria. If you call the method with false parameter, SelectAllRows(false) will always select all data in the grid, even if filtering is applied.
Note Keep in mind that selectAllRows will not select the rows that are deleted.
Deselect All Rows
IgcTreeGridComponent provides a deselectAllRows method, which by default will deselect all data rows, but if filtering is applied will deselect only the rows that match the filter criteria. If you call the method with false parameter, DeselectAllRows(false) will always clear all row selection state even if filtering is applied.
How to get Selected Rows
If you need to see which rows are currently selected, you can get their row IDs with the selectedRows getter.
publicgetSelectedRows() {
const grid = document.getElementById('grid') as IgcTreeGridComponent;
const currentSelection = grid.selectedRows; // return array of row IDs
}
typescript
Additionally, assigning row IDs to selectedRows will allow you to change the grid's selection state.
public mySelectedRows = [1, 2, 3]; // an array of row IDsconstructor() {
const grid = document.getElementById('grid') as IgcTreeGridComponent;
grid.data = this.data;
grid.selectedRows = this.mySelectedRows;
}
ts
Row Selector Templates
You can template header and row selectors in the IgcTreeGridComponent and also access their contexts which provide useful functionality for different scenarios.
By default, the IgcTreeGridComponenthandles all row selection interactions on the row selector's parent container or on the row itself, leaving just the state visualization for the template. Overriding the base functionality should generally be done using the RowSelectionChanging event. In case you implement a custom template with a Click handler which overrides the base functionality, you should stop the event's propagation to preserve the correct row state.
Row Template
To create a custom row selector template, within the igc-tree-grid you can use the rowSelectorTemplate property. From the template you can access the implicitly provided context variable, with properties that give you information about the row's state.
The selected property shows whether the current row is selected or not while the index property can be used to access the row index.
The rowID property can be used to get a reference of an igc-tree-grid row. This is useful when you implement a click handler on the row selector element.
In the above example we are using an IgcCheckboxComponent and we bind rowContext.selected to its checked property. See this in action in our Row Numbering Demo.
Header Template
To create a custom header selector template, within the IgcTreeGridComponent, you can use the headSelectorTemplate property. From the template you can access the implicitly provided context variable, with properties that give you information about the header's state.
The SelectedCount property shows you how many rows are currently selected while totalCount shows you how many rows there are in the IgcTreeGridComponent in total.
This demo shows the usage of custom header and row selectors. The latter uses index to display row numbers and an IgcCheckboxComponent bound to selected.
<!DOCTYPE html><html><head><title>Sample | Ignite UI | Web Components | infragistics</title><metacharset="UTF-8" /><linkrel="shortcut icon"href="https://static.infragistics.com/xplatform/images/browsers/wc.png" ><linkrel="stylesheet"href="https://fonts.googleapis.com/icon?family=Material+Icons" /><linkrel="stylesheet"href="https://fonts.googleapis.com/css?family=Kanit&display=swap" /><linkrel="stylesheet"href="https://fonts.googleapis.com/css?family=Titillium Web" /><linkrel="stylesheet"href="https://static.infragistics.com/xplatform/css/samples/shared.v8.css" /><linkrel="stylesheet"href="/src/index.css"type="text/css" /></head><body><divid="root"><divclass="container sample ig-typography"><divclass="container fill"><igc-tree-gridauto-generate="false"name="treeGrid"id="treeGrid"id="treeGrid"primary-key="ID"foreign-key="ParentID"row-selection="multiple"cell-selection="none"hide-row-selectors="false"><igc-columnfield="Name"data-type="string"></igc-column><igc-columnfield="Title"header="Job Title"></igc-column><igc-columnfield="HireDate"data-type="date"></igc-column><igc-columnfield="Age"data-type="number"></igc-column><igc-columnfield="OnPTO"data-type="boolean"></igc-column></igc-tree-grid></div></div></div><!-- This script is needed only for parcel and it will be excluded for webpack -->
<% if (false) { %><scriptsrc="src/index.ts"></script><% } %>
</body></html>html
/* shared styles are loaded from: *//* https://static.infragistics.com/xplatform/css/samples */css
Excel Style Row Selectors Demo
This demo uses custom templates to resemble Excel-like header and row selectors.
<!DOCTYPE html><html><head><title>Sample | Ignite UI | Web Components | infragistics</title><metacharset="UTF-8" /><linkrel="shortcut icon"href="https://static.infragistics.com/xplatform/images/browsers/wc.png" ><linkrel="stylesheet"href="https://fonts.googleapis.com/icon?family=Material+Icons" /><linkrel="stylesheet"href="https://fonts.googleapis.com/css?family=Kanit&display=swap" /><linkrel="stylesheet"href="https://fonts.googleapis.com/css?family=Titillium Web" /><linkrel="stylesheet"href="https://static.infragistics.com/xplatform/css/samples/shared.v8.css" /><linkrel="stylesheet"href="/src/index.css"type="text/css" /></head><body><divid="root"><divclass="container sample ig-typography"><divclass="container fill"><igc-tree-gridauto-generate="false"name="treeGrid"id="treeGrid"id="treeGrid"primary-key="ID"foreign-key="ParentID"row-selection="multiple"><igc-paginatorname="paginator"id="paginator"per-page="15"select-options="5, 10, 15, 25, 50"></igc-paginator><igc-columnfield="Name"data-type="string"sortable="true"></igc-column><igc-columnfield="Title"header="Job Title"data-type="string"sortable="true"></igc-column><igc-columnfield="HireDate"data-type="date"sortable="true"></igc-column><igc-columnfield="ID"data-type="number"sortable="true"></igc-column><igc-columnfield="Age"data-type="number"sortable="true"></igc-column><igc-columnfield="OnPTO"data-type="boolean"sortable="true"></igc-column></igc-tree-grid></div></div></div><!-- This script is needed only for parcel and it will be excluded for webpack -->
<% if (false) { %><scriptsrc="src/index.ts"></script><% } %>
</body></html>html
This demo prevents some rows from being selected using the RowSelectionChanging event and a custom template with disabled checkbox for non-selectable rows.
import'igniteui-webcomponents-grids/grids/combined';
import { ComponentRenderer, WebTreeGridDescriptionModule } from'igniteui-webcomponents-core';
import { IgcTreeGridComponent } from'igniteui-webcomponents-grids/grids';
import { EmployeesFlatDataItem, EmployeesFlatData } from'./EmployeesFlatData';
import { IgcRowSelectionEventArgs, IgcGridComponent } from'igniteui-webcomponents-grids/grids';
import"igniteui-webcomponents-grids/grids/themes/light/bootstrap.css";
import"./index.css";
exportclassSample{
private treeGrid: IgcTreeGridComponent
private _bind: () =>void;
constructor() {
var treeGrid = this.treeGrid = document.getElementById('treeGrid') as IgcTreeGridComponent;
this.webTreeGridRowSelectionConditional = this.webTreeGridRowSelectionConditional.bind(this);
this._bind = () => {
treeGrid.data = this.employeesFlatData;
treeGrid.addEventListener("rowSelectionChanging", this.webTreeGridRowSelectionConditional);
}
this._bind();
}
private _employeesFlatData: EmployeesFlatData = null;
publicgetemployeesFlatData(): EmployeesFlatData {
if (this._employeesFlatData == null)
{
this._employeesFlatData = new EmployeesFlatData();
}
returnthis._employeesFlatData;
}
private _componentRenderer: ComponentRenderer = null;
publicgetrenderer(): ComponentRenderer {
if (this._componentRenderer == null) {
this._componentRenderer = new ComponentRenderer();
var context = this._componentRenderer.context;
WebTreeGridDescriptionModule.register(context);
}
returnthis._componentRenderer;
}
public webTreeGridRowSelectionConditional(eventArgs: CustomEvent<IgcRowSelectionEventArgs>): void {
const event = eventArgs.detail;
if (!event.added.length && event.removed.length) {
// ignore de-selectreturn;
}
var grid = this.treeGrid;
const originalAddedLength = event.added.length;
// only allow selection for employees that are not pn PTO
event.newSelection = event.newSelection.filter(x => x.OnPTO === true);
// cleanup selection if all conditionally selectable rows are already selectedif (event.newSelection.length
&& !event.newSelection.filter((x: any) => event.oldSelection.indexOf(x) === -1).length
&& originalAddedLength > 1) {
// all selected from header, de-select instead
event.newSelection = [];
}
}
}
new Sample();
ts
<!DOCTYPE html><html><head><title>Sample | Ignite UI | Web Components | infragistics</title><metacharset="UTF-8" /><linkrel="shortcut icon"href="https://static.infragistics.com/xplatform/images/browsers/wc.png" ><linkrel="stylesheet"href="https://fonts.googleapis.com/icon?family=Material+Icons" /><linkrel="stylesheet"href="https://fonts.googleapis.com/css?family=Kanit&display=swap" /><linkrel="stylesheet"href="https://fonts.googleapis.com/css?family=Titillium Web" /><linkrel="stylesheet"href="https://static.infragistics.com/xplatform/css/samples/shared.v8.css" /><linkrel="stylesheet"href="/src/index.css"type="text/css" /></head><body><divid="root"><divclass="container sample ig-typography"><divclass="container fill"><igc-tree-gridauto-generate="false"name="treeGrid"id="treeGrid"id="treeGrid"primary-key="ID"foreign-key="ParentID"row-selection="multiple"><igc-columnfield="Name"data-type="string"></igc-column><igc-columnfield="Title"header="Job Title"></igc-column><igc-columnfield="HireDate"data-type="date"></igc-column><igc-columnfield="Age"data-type="number"></igc-column><igc-columnfield="OnPTO"data-type="boolean"></igc-column></igc-tree-grid></div></div></div><!-- This script is needed only for parcel and it will be excluded for webpack -->
<% if (false) { %><scriptsrc="src/index.ts"></script><% } %>
</body></html>html
/* shared styles are loaded from: *//* https://static.infragistics.com/xplatform/css/samples */css