JavaScript Data GridCell Selection

Cell selection allows Excel-like selection of ranges of cells. Cell selections are useful for visually highlighting data, copying data to the Clipboard, or for doing aggregations using the Status Bar.

Enabling Cell Selection

Cell Selection is enabled by setting the gridOptions.cellSelection to true, or to a configuration object.

const gridOptions = {
    cellSelection: true,

    // other grid options ...
}

When enabled, ranges can be selected in the following ways:

• Mouse Drag: Click the mouse down on a cell and drag and release the mouse over another cell. A range will be created between the two cells and clear any existing ranges.

• Ctrl & Mouse Drag: Holding ^ Ctrl key while creating a range using mouse drag outside an existing range will create a new cell range selection and keep any existing ranges.

• Shift & Click: Clicking on one cell to focus that cell, then holding down ⇧ Shift while clicking another cell, will create a range between both cells.

• Shift & Arrow Keys: Focusing a cell and then holding down ⇧ Shift and using the arrow keys will create a range starting from the focused cell.

• Ctrl & Shift & Arrow Keys: Focusing a cell and then holding down ^ Ctrl + ⇧ Shift and using the arrow keys will create a range starting from the focused cell to the last cell in the direction of the Arrow pressed.

Cell Range Deselection

It is possible to deselect part of existing ranges in the following ways:

• Ctrl & Mouse Drag: Holding ^ Ctrl and dragging a range starting within an existing range will cause any cells covered by the new range to be deselected.

• Ctrl & Click: Holding ^ Ctrl and clicking a cell will deselect just that cell.

Note that deselecting part of a range can split the range into multiple ranges, since individual ranges have the limitation of being rectangular.

The example below demonstrates simple cell selection. Cell ranges can be selected in all the ways described above.

Prevent Selection of Multiple Ranges

By default multiple ranges can be selected. To restrict cell selection to a single range, even if the ^ Ctrl key is held down, set cellSelection.suppressMultiRanges to true.

const gridOptions = {
    cellSelection: {
        suppressMultiRanges: true,
    },

    // other grid options ...
}

The following example demonstrates single range cell selection:

Ranges with Pinning and Floating

It is possible to select a cell 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 to 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 pinned 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 cell selection will work as you would expect in the flattened out version where only full rectangles can be selectable.

Copy Cell Range Down

When you have more than one row selected in a range, pressing keys ^ Ctrl+D will copy the top row values to all other rows in the selected range.

By default, the Value Formatter and Value Parser will be used whilst copying the range via the Use Value Formatter For Export and Use Value Parser for Import features.

Delete Cell Range

When Cell Editing is enabled, pressing the Delete key will clear all of the cells in the range (by setting the cell values to null). If your column uses a valueParser, it will receive an empty string ('') as the new value.

This will also emit the following events:

API Reference

Here you can find a full list of configuration options available in 'cell' mode.

Next up

Continue to the next section to learn about the Range Handle.