Angular Data GridMulti-Row Selection

Enable users to select many rows at once within a grid.

Enabling Multi-Row Selection

To enable multi-row selection set selection.mode to 'multiRow':

<ag-grid-angular
    [selection]="selection"
    /* other grid options ... */ />

this.selection = { 
    mode: 'multiRow' 
};

The following example illustrates a basic multi-row selection configuration.

Click checkboxes to select or deselect a row. Alternatively, hold ^ Ctrl and then click to add or remove rows from the selection. Users can hold ⇧ Shift and then click to add a range of adjacent rows to the selection.

Ranges of rows can be selected by holding down ⇧ Shift while clicking on rows. This behaviour also applies when Checkbox Selection is enabled, and in Group Selection.

Removing Selection Checkboxes

To prevent any row selection checkboxes from being rendered in rows, set selection.checkboxes to false. To prevent the header checkbox from being rendered, set selection.headerCheckbox to false. Setting both to false will disable the checkbox column.

<ag-grid-angular
    [selection]="selection"
    /* other grid options ... */ />

this.selection = {
    mode: 'singleRow',
    checkboxes: false,
    headerCheckbox: false,
};

Configure Selectable Rows

It is possible to specify which rows can be selected via the selection.isRowSelectable callback function.

For instance if we only wanted to allow selection for rows where the 'year' property is less than 2004, we could implement the following:

<ag-grid-angular
    [selection]="selection"
    /* other grid options ... */ />

this.selection = {
    mode: 'multiRow',
    isRowSelectable: (rowNode) => rowNode.data ? rowNode.data.year < 2004 : false,
};

Rows for which isRowSelectable returns false cannot be selected at all, whether using the UI or the API.

Note that this example uses hideDisabledCheckboxes to hide disabled checkboxes, which can be toggled on or off.

Selecting All Rows

All rows may be selected at once by using the header checkbox, which is enabled by default in 'multiRow' mode.

The three possible values of selection.selectAll are:

• 'all': (Default) Selecting the header checkbox selects all selectable rows in the grid.
• 'filtered': Selecting the header checkbox will select all rows that satisfy the currently active filter.
• 'currentPage': Selecting the header checkbox will select all rows that satisfy the currently active filter on the current page.

<ag-grid-angular
    [selection]="selection"
    /* other grid options ... */ />

this.selection = { 
    mode: 'multiRow',
    selectAll: 'filtered'
};

The example below demonstrates the three different modes available for selection.selectAll:

Note that when selection.isRowSelectable is defined, the header checkbox will only select selectable rows.

Customising the Checkbox Column

The checkbox column may be customised in a similar way to any other column, by specifying its column definition in the controlsColDef grid option.

The ControlsColDef allows for a great deal of customisation, including custom renderers, sorting, tooltips and more. The example below demonstrates allowing sorting using the default sort order (selected first) via the header, changing the default width of the column, and pinning it to the left.

<ag-grid-angular
    [controlsColDef]="controlsColDef"
    /* other grid options ... */ />

this.controlsColDef = {
    sortable: true,
    width: 120,
    maxWidth: 120,
    suppressHeaderMenuButton: false,
    pinned: 'left',
};

Prevent Click Selection & Deselection

The selection.suppressClickSelection property configures whether a row's selection state will be impacted when the row is clicked, or when ␣ Space is pressed while the row is focused.

In some scenarios, such as when using Checkbox Selection, it can be preferable to disable other methods of selection, such as with the keyboard (via ␣ Space), selection via row click, and Deselection via Row Click. Both selection and deselection can be disabled by setting suppressClickSelection to true, otherwise they may be disabled separately using the values 'suppressSelection' and 'suppressDeselection'.

<ag-grid-angular
    [selection]="selection"
    /* other grid options ... */ />

this.selection = { 
    mode: 'multiRow',
    suppressClickSelection: true,
};

The example below demonstrates the three possible configurations for this property, as well as the behaviour when it is disabled. Use the select element to switch between modes.

Force Checkboxes to be Selected

It is possible to select a row via the Grid API and disable its checkbox to prevent users from deselecting it. This can be achieved by providing a function to selection.checkboxes.

<ag-grid-angular
    [selection]="selection"
    [onFirstDataRendered]="onFirstDataRendered"
    /* other grid options ... */ />

this.selection = {
    mode: 'multiRow',
    suppressClickSelection: true,
    checkboxes: (params) => params.data && params.data.year === 2012,
};
this.onFirstDataRendered = (params) => {
    const nodesToSelect = [];
    params.api.forEachNode((node) => {
        if (node.data && node.data.year <= 2008 && node.data.year >= 2004) {
            nodesToSelect.push(node);
        }
    });
    params.api.setNodesSelected({ nodes: nodesToSelect, newValue: true });
};

In the example below only rows with Year equal to 2012 can be selected or deselected by the user. The selection.suppressClickSelection setting has been enabled to prevent users from modifying row selection by clicking the row. Clicking the header checkbox, however, will select all rows even if their checkboxes are disabled.

Selecting Multiple Rows without Ctrl or Shift keys

In certain circumstances, especially in the context of touchscreen devices, users may want to select multiple rows without having to use the ^ Ctrl and ⇧ Shift keys.

This can be accomplished by setting the selection.enableMultiSelectWithClick flag to true.

<ag-grid-angular
    [selection]="selection"
    /* other grid options ... */ />

this.selection = {
    mode: 'multiRow',
    checkboxes: false,
    headerCheckbox: false,
    enableMultiSelectWithClick: true,
};

Click multiple rows in the example below without pressing any keyboard keys to explore this behaviour.

API Reference

See the full list of configuration options available in 'multiRow' mode.

Next up

Row selection can be used when using row grouping, tree data and the server side row model. See the respective sections of the documentation:

• Row Group Selection
• Tree Data Selection
• Server-Side Row Model Selection

Continue to the next section to see the Row Selection API reference.