Expand All

  Getting Started

  Interfacing

  Features

  Row Models

  Themes

  Components

  Examples

Misc

Github stars make projects look great. Please help, donate a star, it's free.
Get informed on releases and other ag-Grid news only - never spam.
Follow on Twitter

Selection

When you pass data to the grid, it wraps each data item in an node. This is explained in the section Grid Model. When you query for the selected rows, there are two method types, ones that return nodes, and ones that return data items. To get the selected nodes / rows from the grid, use the following API methods:

  • api.getSelectedNodes(): Returns an array of the selected nodes.
  • api.getSelectedRows(): Returns a array of selected rows data.

Working with the ag-Grid nodes is preferred over the row data as it provide you with more information and maps better to the internal representation of ag-grid.

The following properties are relevant to selection:

  • rowSelection: Type of row selection, set to either 'single' or 'multiple' to enable selection.
  • rowDeselection: Set to true or false. If true, then rows will be deselected if you hold down ctrl + click the row. Normal behaviour with the grid disallows deselection of nodes (ie once a node is selected, it remains selected until another row is selected in it's place).
  • suppressRowClickSelection: If true, rows won't be selected when clicked. Use, for example, when you want checkbox selection, and don't want to also select when the row is clicked.

Example - Single Row Selection

The example below shows single row selection.

Example - Multiple Row Selection

The example below shows multi-row selection.

Checkbox Selection

Checkbox selection can be used in two places: a) row selection and b) group selection.

To include checkbox selection for a column, set the attribute 'checkboxSelection' to true on the column definition. You can set this attribute on as many columns as you like, however it doesn't make sense to have it in more one column in a table.

To enable checkbox selection for groups, set the attribute 'checkbox' to true for the group renderer. See the grouping section for details on the group renderer.

colDef.checkboxSelection can also be a function that returns true/false - use this if you want only checkboxes on some rows but not others. gridOptions.checkboxSelection can also be specified as a function - use this if you want, for example, the first column to have checkbox selection regardless of which column it is (you would do this by looping the columns using the column API, and check if the first column is the current one (in checkboxSelection).

Group Selection

When doing grouping, you control what selecting a group means. This is controlled with the two properties groupSelectsChildren and groupSelectsFiltered.

  • groupSelectsChildren: When true, selecting a group will have the impact of selecting all it's children. The group will then display 'selected' when all children are selected, 'unselected' when none are selected and 'intermediate' when children have a mix of selected and unselected. When the node is selecting children, it will never appear in the selected set when calling api.getSelectedNodes(). When false, then the group is selectable independently of the child nodes.
  • When selecting the group node independently of the children, it will appear in the set when calling api.getSelectedNodes().
  • groupSelectsFiltered: Gets used when groupSelectsChildren=true. When true only filtered children of the group will be selected / unselected. This means you can apply a filter, then try to select a group, the group will end up in the intermediate state as only as subset of the children will be selected.

Groups & Checkbox Selection Example 1

The example below shows checkbox selection with groups. Selecting the group has the effect of selecting the children. Likewise selecting all the children automatically selects the group. In this scenario the group itself will never appear in the selectedRows list.

The example also shows a checkbox for selection on the age column. In practice, it is not normal to have more than two columns for selection, the below is just for demonstration. Having a checkbox within a non-group row is best for grids that are not using grouping.

Groups & Checkbox Selection Example 2 - No Select Leaf Nodes

The example below is similar to the previous example except it does not put checkboxes on the leaf level nodes, only allowing entire groups to be selected. This is achieved by providing functions for colDef.checkboxSelection and groupColumnDef.cellRendererParams.checkbox.

Groups & Checkbox Selection Example 3 - Only Filtered

Lastly we show an example using groupSelectsFiltered=true. Here, when you filter the grid and select a group, only the filtered children get selected.

To demonstrate, try this in the example:

  1. Filter on swimming
  2. Select a country
  3. Notice that all filtered records get selected. If you remove the filter, the non filtered are not selected.
  4. Notice that the group becomes intermediate while all it's filtered children get selected. This is because the selected state of the group node is independent to the filter - so it becomes intermediate as not all of it's children are selected.

Header Checkbox Selection

It is possible to have a checkbox in the header for selection. To configure the column to have checkbox, set colDef.headerCheckboxSelection=true. headerCheckboxSelection can also be a function, if you want the checkbox to appear sometimes (eg if the columns is ordered first in the grid).

// the name column header always has a checkbox in the header
colDef = {
    field: 'name',
    headerCheckboxSelection: true
    ...
}

// the country column header only has checkbox if it is the first column
colDef = {
    field: 'country',
    headerCheckboxSelection: function(params) {
        var displayedColumns = params.columnApi.getAllDisplayedColumns();
        var thisIsFirstColumn = displayedColumns[0] === params.column;
        return thisIsFirstColumn;
    }
    ...
}

If headerCheckboxSelection is a function, the function will be called every time there is a change to the displayed columns, to check for changes.

Select Everything or just Filtered

The header checkbox has two modes of operation, 'normal' and 'filtered only'.

  • colDef.headerCheckboxSelectionFilteredOnly=false: The checkbox will select all rows when checked, and un-select all rows when unchecked. The checkbox will update it's state based on all rows.
  • colDef.headerCheckboxSelectionFilteredOnly=true: The checkbox will select only filtered rows when checked and un-select only filtered rows when unchecked. The checkbox will update it's state base on only filtered rows.
The examples below demonstrate both of these options.

Header Checkbox Example 1 - Filtered Only = true

This example has the following characteristics:

  • The checkbox works on filtered only. That means if you filter first, then hit the checkbox to select or un-select, then only the filtered results get impacted.
  • The checkbox is always on the athlete column, even if the athlete column is moved.

Header Checkbox Example 2 - Filtered Only = false

The next example is similar to the one above with the following changes:

  • The select selects everything, not just filtered.
  • The column that the selection checkbox goes on is always the first column. This can be observed by dragging the columns to reorder them.

Selection Events

There are two events with regards selection:

  • rowSelected: Gets called when a row is selected or deselected. The event contains the node in question, so call the nodes 'isSelected()' method to see if it was just selected or deselected.
  • selectionChanged: Gets called when one or more rows are selected or deselected. Use the grid API get a list of selected nodes if you want them.

Node Selection API

To select rows programmatically, use the node.setSelected() method. This method takes two parameters:

  • selected: set to true to select, false to un-select.
  • clearSelection (optional): for selection only. If true, other nodes selection will be cleared. Use this if you do not want multi selection and want this node to be exclusively selected.
// set selected, keep any other selections
node.setSelected(true);

// set selected, exclusively, remove any other selections
node.setSelected(true, true);

// un-select
node.setSelected(false);

// check status of node selection
var selected = node.isSelected();
The selected status method returns true if the node is selected, or false if it is not selected. If the node is a group node and the group selection is set to 'children', then this will return true if all child (and grand child) nodes are selected, false if all unselected, or undefined if a mixture.

Grid Selection API

The grid API has the following methods for selection:

  • api.selectAll(): Select all rows in the grid. This is independent to filtering, it will always select everything regardless of filtering.
  • api.deselectAll(): Un-select all rows, again regardless of filtering.
  • api.selectAllFiltered(): Select all filtered rows in the grid.
  • api.deselectAllFiltered(): Un-select all filtered rows.
  • api.getSelectedNodes(): Returns a list of all the selected row nodes. This again is regardless of what filters are set.

If you want to select only filtered out rows nodes, then you do this following:

// loop through each node after filter
api.forEachNodeAfterFilter( function(node) {
  // select the node
  node.setSelected(true);
});

Deep Dive Example - Using forEachNode

There is an api function forEachNode. This is useful for doing group selections on a business key. The example below shows selecting all rows with country = 'United States'. This method is also useful when you load data and need to know the node equivalent of the data for selection purposes.

Selection with Keyboard Arrow Keys

By default, you can select a row on mouse click. And you can navigate up and down the rows using your keyboard keys. But the selection state does not correlate with the navigation keys. However, we can add this behaviour using your own Custom Navigation.

First we need to provide a callback to the navigateToNextCell property in gridOptions to override the default arrow key navigation

var gridOptions = {

        // ...

        navigateToNextCell: myNavigation

}

From the code below you can see that we iterate over each node and call the setSelected() method if matches the current rowIndex.

function myNavigation(params) {

   var previousCell = params.previousCellDef;
   var suggestedNextCell = params.nextCellDef;

   var KEY_UP = 38;
   var KEY_DOWN = 40;
   var KEY_LEFT = 37;
   var KEY_RIGHT = 39;

   switch (params.key) {
       case KEY_DOWN:
           previousCell = params.previousCellDef;
           // set selected cell on current cell + 1
           gridOptions.api.forEachNode( (node) => {
               if (previousCell.rowIndex + 1 === node.rowIndex) {
                   node.setSelected(true);
               }
           });
           return suggestedNextCell;
       case KEY_UP:
           previousCell = params.previousCellDef;
           // set selected cell on current cell - 1
           gridOptions.api.forEachNode( (node) => {
               if (previousCell.rowIndex - 1 === node.rowIndex) {
                   node.setSelected(true);
               }
           });
           return suggestedNextCell;
       case KEY_LEFT:
       case KEY_RIGHT:
           return suggestedNextCell;
       default:
           throw "this will never happen, navigation is always on of the 4 keys above";
   }
}