JavaScript 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 rowSelection.mode to 'multiRow':

const gridOptions = {
    rowSelection: { 
        mode: 'multiRow' 
    },

    // other grid options ...
}

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

Click checkboxes to select or deselect a row. Alternatively, you can do this via the keyboard by focusing the row and pressing the ␣ Space key. Users can hold ⇧ Shift and then click a checkbox 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 rowSelection.checkboxes to false. To prevent the header checkbox from being rendered, set rowSelection.headerCheckbox to false. Setting both to false will disable the checkbox column. You will also need to enable click selection by setting enableClickSelection: true.

const gridOptions = {
    rowSelection: {
        mode: 'singleRow',
        checkboxes: false,
        headerCheckbox: false,
        enableClickSelection: true,
    },

    // other grid options ...
}

You may pass a function to rowSelection.checkboxes to dynamically enable or disable checkboxes for given rows.

Configure Selectable Rows

It is possible to specify which rows can be selected via the rowSelection.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:

const gridOptions = {
    rowSelection: {
        mode: 'multiRow',
        isRowSelectable: (rowNode) => rowNode.data ? rowNode.data.year < 2004 : false,
    },

    // other grid options ...
}

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 rowSelection.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.
const gridOptions = {
    rowSelection: { 
        mode: 'multiRow',
        selectAll: 'filtered'
    },

    // other grid options ...
}

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

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

The value of rowSelection.selectAll does not affect group selection behaviour, which is controlled by rowSelection.groupSelects. See Row Grouping - Selecting Groups for more on this.

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 selectionColumnDef grid option.

selectionColumnDef
SelectionColumnDef
Configure the selection column, used for displaying checkboxes. Note that due to the nature of this column, this type is a subset of ColDef, which does not support several normal column features such as editing, pivoting and grouping.

The SelectionColumnDef 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.

const gridOptions = {
    selectionColumnDef: {
        sortable: true,
        width: 120,
        maxWidth: 120,
        suppressHeaderMenuButton: false,
        pinned: 'left',
    },

    // other grid options ...
}

The checkbox column has a default maxWidth set. To make the column resizable (when setting resizable: true), or to set a width/initialWidth, the max width must also be overridden.

Enable Click Selection & Deselection

The rowSelection.enableClickSelection 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.

enableClickSelection
boolean | 'enableDeselection' | 'enableSelection'
default: false
Modifies the selection behaviour when clicking a row, or pressing Space while focusing a row.

This is typically used when Checkbox Selection is disabled, though both can be enabled simultaneously if desired. Click-selection and deselection can be enabled by setting enableClickSelection to true, otherwise they may be enabled separately using the values 'enableSelection' and 'enableDeselection'.

const gridOptions = {
    rowSelection: { 
        mode: 'multiRow',
        enableClickSelection: true,
    },

    // other grid options ...
}

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.

Note that deselection is still possible when checkboxes are enabled by clicking a selected checkbox.

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 rowSelection.checkboxes.

const gridOptions = {
    rowSelection: {
        mode: 'multiRow',
        checkboxes: (params) => params.data && params.data.year === 2012,
    },
    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 });
    },

    // other grid options ...
}

In the example below only rows with Year equal to 2012 can be selected or deselected by the user. Clicking the header checkbox, however, will select all rows even if their checkboxes are disabled.

Selecting Multiple Rows without Ctrl key

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

This can be accomplished by setting the rowSelection.enableSelectionWithoutKeys flag to true. You will also need to set enableClickSelection to true.

const gridOptions = {
    rowSelection: {
        mode: 'multiRow',
        checkboxes: false,
        headerCheckbox: false,
        enableSelectionWithoutKeys: true,
        enableClickSelection: true,
    },

    // other grid options ...
}

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.

mode
'multiRow'
'multiRow'
groupSelects
GroupSelectionMode
default: 'self'
Determine group selection behaviour
selectAll
SelectAllMode
default: 'all'
Determines how "select all" behaviour works. This controls header checkbox selection.
headerCheckbox
boolean
default: true
If true or the callback returns true, a 'select all' checkbox will be put into the header.
enableClickSelection
boolean | 'enableDeselection' | 'enableSelection'
default: false
Modifies the selection behaviour when clicking a row, or pressing Space while focusing a row.
checkboxes
boolean | CheckboxSelectionCallback
default: true
Set to true or return true from the callback to render a selection checkbox.
hideDisabledCheckboxes
boolean
default: false
Set to true to hide a disabled checkbox when row is not selectable and checkboxes are enabled.
isRowSelectable
IsRowSelectable
Callback to be used to determine which rows are selectable. By default rows are selectable, so return false to make a row non-selectable.
copySelectedRows
boolean
When enabled and a row is selected, the copy action should copy the entire row, rather than just the focused cell
enableSelectionWithoutKeys
boolean
default: false
Set to true to allow (possibly multiple) rows to be selected and deselected using single click or touch.

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:

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