Angular Cell Selection
The selection feature enables rich data select capabilities in the Material UI based Tree Grid. Variety of events and single select actions are available thanks to the powerful API and easy to use methods. The Tree Grid now supports three modes for cell selection, and you can easily switch between them by changing cellSelection
property. You can disable cell selection, you can select only one cell within the grid or to select multiple cells in the grid, which is provided as default option.
But let's dive deeper in each of these options.
Angular Cell Selection Example
The sample below demonstrates the three types of Tree Grid's cell 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.
Selection types
Tree Grid Multiple-cell Selection
How to select cells:
- By
Mouse drag
- Rectangular data selection of cells would be performed. - By
Ctrl key
press +Mouse drag
- Multiple range selections would be performed. Any other existing cell selection will be persisted. - Instant multi-cell selection by using Shift key. Select single cell and select another single cell by holding the Shift key. Cell range between the two cells will be selected. Keep in mind that if another second cell is selected while holding
Shift key
the cell selection range will be updated based on the first selected cell position (starting point). - Keyboard multi-cell selection by using the
Arrow keys
while holdingShift key
. Multi-cell selection range will be created based on the focused cell. - Keyboard multi-cell selection by using the
Ctrl + Arrow keys
andCtrl + Home/End
while holdingShift key
. Multi-cell selection range will be created based on the focused cell. - Clicking with the
Left Mouse key
while holdingCtrl key
will add single cell ranges into the selected cells collection. - Continuous multiple cell selection is available, by clicking with the mouse and dragging.
Demo
Tree Grid Single Selection
When you set the [cellSelection]="'single'"
, this allows you to have only one selected cell in the grid at a time. Also the mode mouse drag
will not work and instead of selecting a cell, this will make default text selection.
Note
When single cell is selected selected
event is emitted, no matter if the selection mode
is single
or multiple
. In multi-cell selection mode when you select a range of cells rangeSelected
event is emitted.
Tree Grid None selection
If you want to disable cell selection you can just set [cellSelection]="'none'"
property. In this mode when you click over the cell or try to navigate with keyboard, the cell is not selected, only the activation style
is applied and it is going to be lost when you scroll or click over other element on the page. The only way for you to define selection is by using the API methods that are described below.
Keyboard navigation interactions
While Shift key is pressed
- Shift + Arrow Up to add above cell to the current selection.
- Shift + Arrow Down to add below cell to the current selection.
- Shift + Arrow Left to add left cell to the current selection.
- Shift + Arrow Right to add right cell to the current selection.
While Ctrl + Shift keys are pressed
- Ctrl + Shift + Arrow Up to select all cells above the focused cell in the column.
- Ctrl + Shift + Arrow Down to select all cells below the focused cell in the column.
- Ctrl + Shift + Arrow Left to select all cells till the start of the row.
- Ctrl + Shift + Arrow Right to select all cells till the end of the row.
- Ctrl + Shift + Home to select all cells from the focused cell till the first-most cell in the grid
- Ctrl + Shift + End to select all cells from the focused cell till the last-most cell in the grid
Note
Continuous scroll is possible only within Grid's body.
Api usage
Below are the methods that you can use in order to select ranges, clear selection or get selected cells data.
Select range
selectRange(range)
- Select a range of cells with the API. rowStart
and rowEnd
should use row indexes and columnStart
and columnEnd
could use column index or column data field value.
const range = { rowStart: 2, rowEnd: 2, columnStart: 1, columnEnd: 1 };
this.grid1.selectRange(range);
...
const range = { rowStart: 0, rowEnd: 2, columnStart: 'Name', columnEnd: 'ParentID' };
this.grid1.selectRange(range);
Note
Select range is additive operation. It will not clear your previous selection.
Clear cell selection
clearCellSelection()
will clear the current cell selection.
Get selected data
getSelectedData()
will return array of the selected data in format depending on the selection. Examples below:
- If three different single cells are selected:
expectedData = [
{ CompanyName: 'Infragistics' },
{ Name: 'Michael Langdon' },
{ ParentID: 147 }
];
- If three cells from one column are selected:
expectedData = [
{ Address: 'Obere Str. 57'},
{ Address: 'Avda. de la Constitución 2222'},
{ Address: 'Mataderos 2312'}
];
- If three cells are selected with mouse drag from one row and three columns:
expectedData = [
{ Address: 'Avda. de la Constitución 2222', City: 'México D.F.', ContactTitle: 'Owner' }
];
- If three cells are selected with mouse drag from two rows and three columns:
expectedData = [
{ ContactTitle: 'Sales Agent', Address: 'Cerrito 333', City: 'Buenos Aires'},
{ ContactTitle: 'Marketing Manager', Address: 'Sierras de Granada 9993', City: 'México D.F.'}
];
- If two different ranges are selected:
expectedData = [
{ ContactName: 'Martín Sommer', ContactTitle: 'Owner'},
{ ContactName: 'Laurence Lebihan', ContactTitle: 'Owner'},
{ Address: '23 Tsawassen Blvd.', City: 'Tsawassen'},
{ Address: 'Fauntleroy Circus', City: 'London'}
];
- If two overlapping ranges are selected, the format would be:
expectedData = [
{ ContactName: 'Diego Roel', ContactTitle: 'Accounting Manager', Address: 'C/ Moralzarzal, 86'},
{ ContactName: 'Martine Rancé', ContactTitle: 'Assistant Sales Agent', Address: '184, chaussée de Tournai', City: 'Lille'},
{ ContactName: 'Maria Larsson', ContactTitle: 'Owner', Address: 'Åkergatan 24', City: 'Bräcke'},
{ ContactTitle: 'Marketing Manager', Address: 'Berliner Platz 43', City: 'München'}
];
Note
selectedCells()
will return cells from all visible rows (rows in the grid's view port) and from all columns, including columns that are out of view. getSelectedData()
will also return the selected cell data.
getSelectedRanges(): GridSelectionRange[]
will return the current selected ranges in the grid from both keyboard and pointer interactions. The type is GridSelectionRange[].
Features integration
The multi-cell selection is index based (DOM elements selection).
Sorting
- When sorting is performed selection will not be cleared. It will leave currently selected cells the same while sorting ascending or descending.Paging
- On paging selected cells will be cleared. Selection wont be persisted across pages.Filtering
- When filtering is performed selection will not be cleared. If filtering is cleared it will return - the initially selected cells.Resizing
- On column resizing selected cells will not be cleared.Hiding
- It will not clear the selected cells. If column is hidden, the cells from the next visible column will be selected.Pinning
- Selected cell will not be cleared. Same as hidingGroup by
- On column grouping selected cells will not be cleared.
Styling Guidelines
The theme engine exposes properties that allows us to style the range of selected cells
.
Import theme
To get started with styling the selection, we need to import the index
file, where all the theme functions and component mixins live:
@use "igniteui-angular/theming" as *;
// IMPORTANT: Prior to Ignite UI for Angular version 13 use:
// @import '~igniteui-angular/lib/core/styles/themes/index';
Define colors
Once done, we can make use of the igx-contrast-color
and igx-color
functions. With them, we define the colors we would like to use for our selection range:
$text-color:contrast-color($default-palette, 'primary', 900);
$background-color: color($default-palette, "primary", 900);
$border-yellow: #f2c43c;
Create custom theme
Next we create a new theme that extends the grid-theme
passing our text-color
, background-color
and border-yellow
variables as $cell-selected-text-color
, $cell-selected-background
and $cell-active-border-color
, respectively:
$custom-grid-theme: grid-theme(
$cell-selected-text-color: $text-color,
$cell-active-border-color: $border-yellow,
$cell-selected-background: $background-color
);
Apply theme
Afterwards, all we need to do is include the mixin in our component's style (could also be in the app styles), so that our igx-tree-grid uses the newly created theme instead of the default one:
@include grid($custom-grid-theme);
Note
If the component is using an Emulated ViewEncapsulation
, it is necessary to penetrate this encapsulation using ::ng-deep
.
We scope the style under :host
selector so as not to affect any other grids we might have in our application.
:host {
::ng-deep {
@include grid($custom-grid-theme);
}
}
With the custom theme applied, the selected grid cells are highlighted with our selected colors:
Demo
Note
The sample will not be affected by the selected global theme from Change Theme
.
API References
Additional Resources
- Tree Grid overview
- Selection
- Row selection
- Filtering
- Sorting
- Summaries
- Column Moving
- Column Pinning
- Column Resizing
- Virtualization and Performance