---
title: "Cell Selection API Reference"
enterprise: true
framework: vue
version: "36.1.0"
---

# Cell Selection API Reference

## Configuration API

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `suppressMultiRanges` | `boolean` |  | `false` | If `true`, only a single range can be selected |
| `enableHeaderHighlight` | `boolean` |  | `false;` | If `true` the header of cells containing ranges will be highlighted. |
| `enableColumnSelection` | `boolean` |  | `false` | If `true`, allows selection of a column of cells when clicking the column header. |
| `handle` | `RangeHandleOptions \| FillHandleOptions` |  |  | Determine the selection handle behaviour. Can be used to configure the range handle and the fill handle. |

## Selection Events

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `cellSelectionChanged` | `CellSelectionChangedEvent` |  |  | A change to cell selection has occurred. |
| `fillStart` | `FillStartEvent` |  |  | Fill operation has started. |
| `fillEnd` | `FillEndEvent` |  |  | Fill operation has ended. |

As an example to illustrate the `cellSelectionChanged` event, if selecting a range of 5 cells in a row, the user will click the first cell and drag to the last cell. This will result in up to 7 events. The first and last cell in the range will cause two events each. This is due to the first cell firing an event with `started=true, finished=true` upon mousedown with an additional event `started=true, finished=false` while in the range, and the last cell firing an event `started=false, finished=false` as soon as it is in the range and then again `started=false, finished=true` upon the end of cell selection. All the intermediary events will have one event with both `started` and `finished` as `false`. This is illustrated in the table:

| User action | `started` | `finished` |
| --- | --- | --- |
| `mousedown` in first cell | `true` | `true` |
| `mousemove` in first cell | `true` | `false` |
| `mousemove` in intermediate cells | `false` | `false` |
| `mousemove` in final cell | `false` | `false` |
| `mouseup` in final cell | `false` | `true` |

The example below also illustrates this by logging the event fields in the console:

#### cellSelectionChanged

```ts
import {
  createApp,
  defineComponent,
  onBeforeMount,
  ref,
  shallowRef,
} from "vue";
import { AgGridVue } from "ag-grid-vue3";
import {
  CellSelectionOptions,
  ClientSideRowModelModule,
  ColDef,
  ColGroupDef,
  GridApi,
  GridOptions,
  GridReadyEvent,
  ModuleRegistry,
  enableDevValidations,
} from "ag-grid-community";
import {
  CellSelectionModule,
  ClipboardModule,
  ColumnMenuModule,
  ContextMenuModule,
} from "ag-grid-enterprise";
import { IOlympicData } from "./interfaces";
if (process.env.NODE_ENV !== "production") {
  enableDevValidations();
}

ModuleRegistry.registerModules([
  ClientSideRowModelModule,
  ClipboardModule,
  ColumnMenuModule,
  ContextMenuModule,
  CellSelectionModule,
]);

const VueExample = defineComponent({
  template: `
        <div style="height: 100%">
                <ag-grid-vue
      style="width: 100%; height: 100%;"
      @grid-ready="onGridReady"
      :columnDefs="columnDefs"
      :defaultColDef="defaultColDef"
      :cellSelection="true"
      :rowData="rowData"
      @cell-selection-changed="onCellSelectionChanged"></ag-grid-vue>
        </div>
    `,
  components: {
    "ag-grid-vue": AgGridVue,
  },
  setup(props) {
    const gridApi = shallowRef<GridApi<IOlympicData> | null>(null);
    const columnDefs = ref<ColDef[]>([
      { field: "athlete", minWidth: 150 },
      { field: "age", maxWidth: 90 },
      { field: "country", minWidth: 150 },
      { field: "year", maxWidth: 90 },
      { field: "date", minWidth: 150 },
      { field: "sport", minWidth: 150 },
      { field: "gold" },
      { field: "silver" },
      { field: "bronze" },
      { field: "total" },
    ]);
    const defaultColDef = ref<ColDef>({
      flex: 1,
      minWidth: 100,
    });
    const rowData = ref<IOlympicData[]>(null);

    function onCellSelectionChanged(e: unknown) {
      console.log(e);
    }
    const onGridReady = (params: GridReadyEvent) => {
      gridApi.value = params.api;

      const updateData = (data) => (rowData.value = data);

      fetch("https://www.ag-grid.com/example-assets/small-olympic-winners.json")
        .then((resp) => resp.json())
        .then((data) => updateData(data));
    };

    return {
      gridApi,
      columnDefs,
      defaultColDef,
      rowData,
      onGridReady,
      onCellSelectionChanged,
    };
  },
});

const app = createApp(VueExample);
app.mount("#app");
```

[Live example: cellSelectionChanged](https://www.ag-grid.com/examples/cell-selection-api-reference/range-selection-changed-event/vue3)

## Editing Events

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `cellEditRequest` | `CellEditRequestEvent` |  |  | Value has changed after editing. Only fires when `readOnlyEdit=true`. |
| `cellSelectionDeleteStart` | `CellSelectionDeleteStartEvent` |  |  | Cell selection delete operation (cell clear) has started. |
| `cellSelectionDeleteEnd` | `CellSelectionDeleteEndEvent` |  |  | Cell selection delete operation (cell clear) has ended. |

## Cell Selection API

The following methods are available on the `GridApi` for managing cell selection.

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `getCellRanges` | `Function` |  |  | Returns the list of selected cell ranges. 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 have dragged up. Module: [`CellSelectionModule`](https://www.ag-grid.com/vue-data-grid/modules/). |
| `addCellRange` | `Function` |  |  | Adds the provided cell range to the selected ranges. This keeps any previous ranges. If you wish to only have the new range selected, then call `clearCellSelection()` first. Module: [`CellSelectionModule`](https://www.ag-grid.com/vue-data-grid/modules/). |
| `clearCellSelection` | `Function` |  |  | Clears the selected cell ranges. Module: [`CellSelectionModule`](https://www.ag-grid.com/vue-data-grid/modules/). |

Cell ranges are normally bounded by a start and end row. However it is also possible to define a range unbounded by rows (i.e. to contain all rows). When adding an unbounded range via `gridApi.addCellRange`, do not provide start or end row positions.

Row positions are defined by a row index and pinned. Row indexes are integers starting at zero. Pinned can be either `'top'` (row is in pinned top section), `'bottom'` (row is in pinned bottom section) or `null` (row is in the main body). See [Row Pinning](https://www.ag-grid.com/vue-data-grid/row-pinning/) for information on row pinning.

Ranges are defined by a list of columns. Pass in either a) a list of columns or b) a start and end column and let the grid work out the columns in between. Passing a list of columns instead of a start and end column has the advantage that the columns do not need to be contiguous.