JavaScript Data GridSingle Row Selection

Version 36.3.0

Enable users to select a single row within a grid.

Enabling Single Row Selection Copy Link

To enable single row selection set rowSelection.mode to 'singleRow'.

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

    // other grid options ...
}

The example below uses this configuration to restrict selection to a single row

main.ts

import {
  ClientSideRowModelModule,
  GridApi,
  GridOptions,
  GridStateModule,
  ModuleRegistry,
  RowSelectionModule,
  createGrid,
  enableDevValidations,
} from "ag-grid-community";
import {
  ColumnMenuModule,
  ColumnsToolPanelModule,
  ContextMenuModule,
  RowGroupingModule,
} from "ag-grid-enterprise";
import { IOlympicData } from "./interfaces";

if (process.env.NODE_ENV !== "production") {
  // Enable extended validations only for development
  enableDevValidations();
}

ModuleRegistry.registerModules([
  RowSelectionModule,
  GridStateModule,
  ClientSideRowModelModule,
  ColumnsToolPanelModule,
  ColumnMenuModule,
  ContextMenuModule,
  RowGroupingModule,
]);

let gridApi: GridApi<IOlympicData>;

const gridOptions: GridOptions<IOlympicData> = {
  columnDefs: [
    { field: "athlete", minWidth: 150 },
    { field: "age", maxWidth: 90 },
    { field: "year", maxWidth: 90 },
    { field: "sport", minWidth: 150 },
    { field: "gold" },
    { field: "silver" },
    { field: "bronze" },
  ],
  defaultColDef: {
    flex: 1,
    minWidth: 100,
  },
  rowSelection: { mode: "singleRow" },
  initialState: {
    rowSelection: ["2"],
  },
};

const gridDiv = document.querySelector<HTMLElement>("#myGrid")!;
gridApi = createGrid(gridDiv, gridOptions);

fetch("https://www.ag-grid.com/example-assets/small-olympic-winners.json")
  .then((response) => response.json())
  .then((data: IOlympicData[]) => gridApi.setGridOption("rowData", data));

Deselect a row by clicking its checkbox. Alternatively, you can do this via the keyboard by focusing the row and pressing the ␣ Space key.

Removing Selection Checkboxes Copy Link

To prevent any row selection checkboxes from being rendered, set rowSelection.checkboxes to false. You will also need to enable click selection by setting enableClickSelection: true.

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

    // other grid options ...
}

main.ts

import {
  ClientSideRowModelModule,
  GridApi,
  GridOptions,
  GridStateModule,
  ModuleRegistry,
  RowSelectionModule,
  createGrid,
  enableDevValidations,
} from "ag-grid-community";
import {
  ColumnMenuModule,
  ColumnsToolPanelModule,
  ContextMenuModule,
  RowGroupingModule,
} from "ag-grid-enterprise";
import { IOlympicData } from "./interfaces";

if (process.env.NODE_ENV !== "production") {
  // Enable extended validations only for development
  enableDevValidations();
}

ModuleRegistry.registerModules([
  RowSelectionModule,
  GridStateModule,
  ClientSideRowModelModule,
  ColumnsToolPanelModule,
  ColumnMenuModule,
  ContextMenuModule,
  RowGroupingModule,
]);

let gridApi: GridApi<IOlympicData>;

const gridOptions: GridOptions<IOlympicData> = {
  columnDefs: [
    { field: "athlete", minWidth: 150 },
    { field: "age", maxWidth: 90 },
    { field: "year", maxWidth: 90 },
    { field: "sport", minWidth: 150 },
    { field: "gold" },
    { field: "silver" },
    { field: "bronze" },
  ],
  defaultColDef: {
    flex: 1,
    minWidth: 100,
  },
  rowSelection: {
    mode: "singleRow",
    checkboxes: false,
    enableClickSelection: true,
  },
  initialState: {
    rowSelection: ["2"],
  },
};

const gridDiv = document.querySelector<HTMLElement>("#myGrid")!;
gridApi = createGrid(gridDiv, gridOptions);

fetch("https://www.ag-grid.com/example-assets/small-olympic-winners.json")
  .then((response) => response.json())
  .then((data: IOlympicData[]) => gridApi.setGridOption("rowData", data));

Setting rowSelection.checkboxes to the boolean false removes the checkboxes entirely. Passing a function instead keeps the checkboxes present and enables or disables them per row: a selectable row for which the function returns false shows a disabled checkbox rather than removing it.

For rows where both isRowSelectable and rowSelection.checkboxes return false, checkboxes will be hidden, rather than disabled.

Selection via Row Numbers Copy Link

When Row Numbers are enabled, clicking a Row Number selects the row, provided click selection is enabled. This gives users a dedicated click target for selecting rows when the checkboxes have been removed.

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

    // other grid options ...
}

If Cell Selection is also enabled, a Row Number click selects the row and the cells in it. To leave only the row selected, see Suppressing Cell Selection Integration.

Configure Selectable Rows Copy Link

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 2007, we could implement the following:

const gridOptions = {
    rowSelection: {
        mode: 'singleRow',
        isRowSelectable: (rowNode) => rowNode.data ? rowNode.data.year < 2007 : false,
        hideDisabledCheckboxes: true
    },

    // other grid options ...
}

Rows for which isRowSelectable returns false cannot be selected at all, whether using the UI or the API.

main.ts

import {
  ClientSideRowModelModule,
  GridApi,
  GridOptions,
  ModuleRegistry,
  RowSelectionModule,
  createGrid,
  enableDevValidations,
} from "ag-grid-community";
import {
  ColumnMenuModule,
  ColumnsToolPanelModule,
  ContextMenuModule,
  RowGroupingModule,
} from "ag-grid-enterprise";
import { IOlympicData } from "./interfaces";

if (process.env.NODE_ENV !== "production") {
  // Enable extended validations only for development
  enableDevValidations();
}

ModuleRegistry.registerModules([
  RowSelectionModule,
  ClientSideRowModelModule,
  ColumnsToolPanelModule,
  ColumnMenuModule,
  ContextMenuModule,
  RowGroupingModule,
]);

let gridApi: GridApi<IOlympicData>;

const gridOptions: GridOptions<IOlympicData> = {
  columnDefs: [
    { field: "year", maxWidth: 120 },
    { field: "athlete" },
    { field: "sport" },
  ],
  defaultColDef: {
    flex: 1,
    minWidth: 100,
  },
  rowSelection: {
    mode: "singleRow",
    hideDisabledCheckboxes: true,
    isRowSelectable: (rowNode) =>
      rowNode.data ? rowNode.data.year < 2007 : false,
  },
};

function toggleHideCheckbox() {
  gridApi.setGridOption("rowSelection", {
    mode: "singleRow",
    isRowSelectable: (rowNode) =>
      rowNode.data ? rowNode.data.year < 2007 : false,
    hideDisabledCheckboxes: getCheckboxValue("#toggle-hide-checkbox"),
  });
}

const gridDiv = document.querySelector<HTMLElement>("#myGrid")!;
gridApi = createGrid(gridDiv, gridOptions);

fetch("https://www.ag-grid.com/example-assets/small-olympic-winners.json")
  .then((response) => response.json())
  .then((data: IOlympicData[]) => gridApi!.setGridOption("rowData", data));

function getCheckboxValue(id: string): boolean {
  return document.querySelector<HTMLInputElement>(id)?.checked ?? false;
}

if (typeof window !== "undefined") {
  // Attach external event handlers to window so they can be called from index.html
  (<any>window).toggleHideCheckbox = toggleHideCheckbox;
}

Note this example uses hideDisabledCheckboxes to hide disabled checkboxes, which can be toggled on or off.

Customising the Checkbox Column Copy Link

The checkbox column may be customised in a similar way to any other column, including custom renderers and tooltips, by specifying its column definition in the selectionColumnDef grid option.

By default, the checkbox column:

is locked to the left edge of the grid (the right edge with RTL), and cannot be moved by users (lockPosition, suppressMovable)
is 50px wide, and cannot be resized (initialWidth, resizable)
cannot be sorted (sortable)
has no header menu button (suppressHeaderMenuButton)
is not editable, has no fill handle, and is not offered as chart data in Integrated Charts

Override the properties in brackets in selectionColumnDef. For example, set both suppressMovable and lockPosition to false to let users drag the column to reorder, pin or unpin it.

Updating selectionColumnDef updates the column as Updating Column Definitions does for any column: an attribute the update leaves out, such as width, pinned or flex, keeps its current state, null clears pinned or flex, and a width applies on every update that sets it unless the column is flexing. To give the column a starting width that the user's resizing keeps, set initialWidth instead of width. Setting an equal selectionColumnDef again changes nothing, as setting the same object does.

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 example below demonstrates the following configuration:

allowing sorting using the default sort order (selected first) via the header menu
changing the default width of the column
allowing resizing
adding some header tooltip text

const gridOptions = {
    selectionColumnDef: {
        sortable: true,
        resizable: true,
        width: 100,
        suppressHeaderMenuButton: false,
        headerTooltip: 'Checkboxes indicate selection',
    },

    // other grid options ...
}

main.ts

import {
  ClientSideRowModelModule,
  GridApi,
  GridOptions,
  ModuleRegistry,
  RowSelectionModule,
  TooltipModule,
  createGrid,
  enableDevValidations,
} from "ag-grid-community";
import {
  ColumnMenuModule,
  ColumnsToolPanelModule,
  ContextMenuModule,
  RowGroupingModule,
} from "ag-grid-enterprise";
import { IOlympicData } from "./interfaces";

if (process.env.NODE_ENV !== "production") {
  // Enable extended validations only for development
  enableDevValidations();
}

ModuleRegistry.registerModules([
  RowSelectionModule,
  TooltipModule,
  ClientSideRowModelModule,
  ColumnsToolPanelModule,
  ColumnMenuModule,
  ContextMenuModule,
  RowGroupingModule,
]);

let gridApi: GridApi<IOlympicData>;

const gridOptions: GridOptions<IOlympicData> = {
  columnDefs: [
    { field: "athlete" },
    { field: "sport" },
    { field: "year", maxWidth: 120 },
  ],
  defaultColDef: {
    flex: 1,
    minWidth: 100,
  },
  rowSelection: { mode: "singleRow" },
  selectionColumnDef: {
    sortable: true,
    resizable: true,
    width: 100,
    suppressHeaderMenuButton: false,
    headerTooltip: "Checkboxes indicate selection",
  },
};

const gridDiv = document.querySelector<HTMLElement>("#myGrid")!;
gridApi = createGrid(gridDiv, gridOptions);

fetch("https://www.ag-grid.com/example-assets/small-olympic-winners.json")
  .then((response) => response.json())
  .then((data: IOlympicData[]) => gridApi.setGridOption("rowData", data));

When sorting by the checkbox column, selecting a new row will not automatically update the row order, see Change Detection for more information.

The checkbox column is sized statically, and is therefore not affected by Auto-Sizing.

Enable Click Selection & Deselection Copy Link

The rowSelection.enableClickSelection property configures whether a row's selection state will be impacted when the row is clicked.

boolean | 'enableDeselection' | 'enableSelection'

default: false

Modifies the selection behaviour when clicking a row. Choosing 'enableSelection' allows selection of a row by clicking the row itself. Choosing 'enableDeselection' allows deselection of a row by CTRL-clicking the row itself. Choosing true allows both selection of a row by clicking and deselection of a row by CTRL-clicking. Choosing false prevents rows from being selected or deselected by clicking.

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: 'singleRow',
        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. Click a row to select it, or ^ Ctrl⌘ Command-click a row to deselect it. Use the select element to switch between modes.

main.ts

import {
  ClientSideRowModelModule,
  GridApi,
  GridOptions,
  ModuleRegistry,
  RowSelectionModule,
  createGrid,
  enableDevValidations,
} from "ag-grid-community";
import {
  ColumnMenuModule,
  ColumnsToolPanelModule,
  ContextMenuModule,
  RowGroupingModule,
} from "ag-grid-enterprise";
import { IOlympicData } from "./interfaces";

if (process.env.NODE_ENV !== "production") {
  // Enable extended validations only for development
  enableDevValidations();
}

ModuleRegistry.registerModules([
  RowSelectionModule,
  ClientSideRowModelModule,
  ColumnsToolPanelModule,
  ColumnMenuModule,
  ContextMenuModule,
  RowGroupingModule,
]);

let gridApi: GridApi<IOlympicData>;

const gridOptions: GridOptions<IOlympicData> = {
  columnDefs: [
    { 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" },
  ],
  defaultColDef: {
    flex: 1,
    minWidth: 100,
  },
  rowSelection: {
    mode: "singleRow",
    enableClickSelection: true,
  },
};

const gridDiv = document.querySelector<HTMLElement>("#myGrid")!;
gridApi = createGrid(gridDiv, gridOptions);

fetch("https://www.ag-grid.com/example-assets/small-olympic-winners.json")
  .then((response) => response.json())
  .then((data: IOlympicData[]) => gridApi.setGridOption("rowData", data));

function onEnableClickSelection() {
  const value =
    document.querySelector<HTMLSelectElement>("#select-enable")?.value;

  gridApi.setGridOption("rowSelection", {
    mode: "singleRow",
    enableClickSelection:
      value === "true" ? true : value === "false" ? false : (value as any),
  });
}

if (typeof window !== "undefined") {
  // Attach external event handlers to window so they can be called from index.html
  (<any>window).onEnableClickSelection = onEnableClickSelection;
}

Note that deselection is still possible using the ␣ Space key or when checkboxes are enabled by clicking a selected checkbox.

API Reference Copy Link

See the full list of configuration options available in 'singleRow' mode.

'singleRow'

boolean | 'enableDeselection' | 'enableSelection'

default: false

Modifies the selection behaviour when clicking a row. Choosing 'enableSelection' allows selection of a row by clicking the row itself. Choosing 'enableDeselection' allows deselection of a row by CTRL-clicking the row itself. Choosing true allows both selection of a row by clicking and deselection of a row by CTRL-clicking. Choosing false prevents rows from being selected or deselected by clicking.

boolean | CheckboxSelectionCallback

default: true

Set to true or return true from the callback to render a selection checkbox.

CheckboxLocation

default: 'selectionColumn'

Configure where checkboxes are displayed. Choosing 'selectionColumn' displays checkboxes in a dedicated selection column. Choosing 'autoGroupColumn' displays checkboxes in the autoGroupColumn. This applies to row checkboxes and header checkboxes.

boolean

default: false

Set to true to hide a disabled checkbox when row is not selectable and checkboxes are enabled.

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.

boolean

default: false

When enabled and a row is selected, the copy action should copy the entire row, rather than just the focused cell

boolean

default: false

Set to true to allow (possibly multiple) rows to be selected and deselected using single click or touch.

'self' | 'detail'

default: 'self'

Determines the selection behaviour of master rows with respect to their detail cells. When set to 'self', selecting the master row has no effect on the selection state of the detail row. When set to 'detail', selecting the master row behaves the same as the header checkbox of the detail grid.

Getting Started

AI Features

Layout & Styling

Charting

Core Features

Advanced Features

JavaScript Data GridSingle Row Selection

Enabling Single Row Selection Copy Link

Removing Selection Checkboxes Copy Link

Selection via Row Numbers Copy Link

Configure Selectable Rows Copy Link

Customising the Checkbox Column Copy Link

Enable Click Selection & Deselection Copy Link

API Reference Copy Link