Expand All

  Getting Started

  Interfacing

  Features

  Row Models

  Themes

  Components

  Examples

  Third Party

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

Range Selection

Range selection allows Excel-like range selection of cells. Once enabled, you can drag the mouse over a set of cells to select a range of cells.

Selecting Multiple Ranges

To select multiple ranges, hold down ctrl while making the selection.

Ranges with Pinning and Floating

It is possible to select a range that spans pinned and non-pinned sections of the grid. If you do this, the selected range will not have any gaps with regards the column order. For example, if you start the drag on the left pinned area and drag to the right pinned area, then all of the columns in the center area will also be part of the range.

Likewise with floating, no row gaps will occur if a range spans into floating rows. A range will be continuous between the floating top rows, the center, and the floating bottom rows.

The above two (pinning and floating) can be thought of as follows: If you have a grid with pinning and / or floating, then 'flatten out' the grid in your head so that all rows and columns are visible, then the range selection will work as you would expect in the flattened out version with only full rectangles can be selectable.

Range Change Event

There is one event rangeSelectionChanged to tell you the range selection has changed. The event has two properties, started and finished, which are true when the selection is starting or finishing. For example, if selecting a range of 10 cells in a row, the user will click the first cell and drag to the last cell. This will result in up to 11 events. The first event will have started=true, the last will have finished=true, and all the intermediary events will have both of these values as false.

api.addEventListener('rangeSelectionChanged', function(event) {
    // this prints true for first event only
    console.log('has changed, started = ' + event.started);
    // this prints true for last event only
    console.log('has changed, finished = ' + event.finished);
});

Range Selection API

api.getRangeSelections()

Get the selected ranges using api.getRangeSelections(). This will return back a list of range selection objects, each object contain the details of one range. The structure of the range selection is as follows:

RangeSelection {
    start: GridCell; // the start cell of the range
    end: GridCell; // the end cell of the range
    columns: Column[]; // all the columns of the range
}

GridCell {
    rowIndex: number; // the index of the row. indexes are zero based.
    floating: string; // whether the row is floating ('top', 'bottom' or null for not floating)
    column: Column; // the column of the cell
}

The start and end will be the cells the user started the drag on. Two things to notice about the start and end:

  • The start is the first cell the user clicked on and the end is the cell where the user stopped dragging. Do not assume that the start cell's index is numerically before the end cell, as the user could of dragged up. Likewise for columns, the end cell could be to the left or the right of the start cell.
  • The columns are listed twice, with start / end columns as well as a complete column list. This is because the complete list of columns may not be what you expect, as the grid may display the columns in a different order to what you provided the grid (the user could reorder), or columns may be not visible, or column groups may be closed. To avoid all ambiguity, the exact columns in the range are presented individually in the columns list.

api.clearRangeSelection()

Clears the range selection.

api.addRangeSelection(rangeSelection)

Adds a range to the selection. This keeps any prevoius ranges. If you wish to have this range exclusively, then call clearRangeSelection() first.

AddRangeSelectionParams{
    rowStart: number, // the start row index
    floatingStart: string, // the starting floating ('top', 'bottom' or null/undefined)
    rowEnd: number, // the end row index
    floatingEnd: string, // the end floating ('top', 'bottom' or null/undefined)
    columnStart: Column|ColDef|string, // colId of the starting column
    columnEnd: Column|ColDef|string // colId of the ending column
}

Callback processCellForClipboard()

There is a grid callback processCellForClipboard() that allows you to format cells before going to the clipboard. This can be useful if, for example, you are pasting to Excel and you need to format dates so that Excel can understand them.

The callback params has the following attributes: value, node, column, api, columnApi, context.

Range Selection Example

The example below demonstrates range selection. Use your mouse to drag over the cells to create selections. Hold down ctrl to select more than one range. The example listens for the rangeSelectionChanged event and creates a sum of all the number values that are in the range (it ignores all non-number values). The finished flag is used to update the eager and lazy figures separately.

The example also shows use of processCellForClipboard() and processCellFromClipboard() by making all the athlete names upper case when copying into the clipboard and lowercase when copying it from the clipboard.