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 rowSelection = useMemo(() => {
return {
mode: 'singleRow'
};
}, []);
<AgGridReact rowSelection={rowSelection} />The example below uses this configuration to restrict selection to a single row
"use client";
import React, {
useCallback,
useMemo,
useRef,
useState,
StrictMode,
} from "react";
import { createRoot } from "react-dom/client";
import { AgGridReact, AgGridProvider } from "ag-grid-react";
import {
ClientSideRowModelModule,
ColDef,
ColGroupDef,
GridApi,
GridOptions,
GridState,
GridStateModule,
ModuleRegistry,
RowSelectionModule,
RowSelectionOptions,
enableDevValidations,
} from "ag-grid-community";
import {
ColumnMenuModule,
ColumnsToolPanelModule,
ContextMenuModule,
RowGroupingModule,
} from "ag-grid-enterprise";
import { IOlympicData } from "./interfaces";
import { useFetchJson } from "./useFetchJson";
if (process.env.NODE_ENV !== "production") {
// Enable extended validations only for development
enableDevValidations();
}
const modules = [
RowSelectionModule,
GridStateModule,
ClientSideRowModelModule,
ColumnsToolPanelModule,
ColumnMenuModule,
ContextMenuModule,
RowGroupingModule,
];
const GridExample = () => {
const containerStyle = useMemo(() => ({ width: "100%", height: "100%" }), []);
const gridStyle = useMemo(() => ({ height: "100%", width: "100%" }), []);
const [columnDefs, setColumnDefs] = useState<ColDef[]>([
{ field: "athlete", minWidth: 150 },
{ field: "age", maxWidth: 90 },
{ field: "year", maxWidth: 90 },
{ field: "sport", minWidth: 150 },
{ field: "gold" },
{ field: "silver" },
{ field: "bronze" },
]);
const defaultColDef = useMemo<ColDef>(() => {
return {
flex: 1,
minWidth: 100,
};
}, []);
const rowSelection = useMemo<
RowSelectionOptions | "single" | "multiple"
>(() => {
return { mode: "singleRow" };
}, []);
const initialState = useMemo<GridState>(() => {
return {
rowSelection: ["2"],
};
}, []);
const { data, loading } = useFetchJson<IOlympicData>(
"https://www.ag-grid.com/example-assets/small-olympic-winners.json",
);
return (
<AgGridProvider modules={modules}>
<div style={containerStyle}>
<div style={gridStyle}>
<AgGridReact<IOlympicData>
rowData={data}
loading={loading}
columnDefs={columnDefs}
defaultColDef={defaultColDef}
rowSelection={rowSelection}
initialState={initialState}
/>
</div>
</div>
</AgGridProvider>
);
};
const root = createRoot(document.getElementById("root")!);
root.render(
<StrictMode>
<GridExample />
</StrictMode>,
);
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 rowSelection = useMemo(() => {
return {
mode: 'singleRow',
checkboxes: false,
enableClickSelection: true,
};
}, []);
<AgGridReact rowSelection={rowSelection} />"use client";
import React, {
useCallback,
useMemo,
useRef,
useState,
StrictMode,
} from "react";
import { createRoot } from "react-dom/client";
import { AgGridReact, AgGridProvider } from "ag-grid-react";
import {
ClientSideRowModelModule,
ColDef,
ColGroupDef,
GridApi,
GridOptions,
GridState,
GridStateModule,
ModuleRegistry,
RowSelectionModule,
RowSelectionOptions,
enableDevValidations,
} from "ag-grid-community";
import {
ColumnMenuModule,
ColumnsToolPanelModule,
ContextMenuModule,
RowGroupingModule,
} from "ag-grid-enterprise";
import { IOlympicData } from "./interfaces";
import { useFetchJson } from "./useFetchJson";
if (process.env.NODE_ENV !== "production") {
// Enable extended validations only for development
enableDevValidations();
}
const modules = [
RowSelectionModule,
GridStateModule,
ClientSideRowModelModule,
ColumnsToolPanelModule,
ColumnMenuModule,
ContextMenuModule,
RowGroupingModule,
];
const GridExample = () => {
const containerStyle = useMemo(() => ({ width: "100%", height: "100%" }), []);
const gridStyle = useMemo(() => ({ height: "100%", width: "100%" }), []);
const [columnDefs, setColumnDefs] = useState<ColDef[]>([
{ field: "athlete", minWidth: 150 },
{ field: "age", maxWidth: 90 },
{ field: "year", maxWidth: 90 },
{ field: "sport", minWidth: 150 },
{ field: "gold" },
{ field: "silver" },
{ field: "bronze" },
]);
const defaultColDef = useMemo<ColDef>(() => {
return {
flex: 1,
minWidth: 100,
};
}, []);
const rowSelection = useMemo<
RowSelectionOptions | "single" | "multiple"
>(() => {
return {
mode: "singleRow",
checkboxes: false,
enableClickSelection: true,
};
}, []);
const initialState = useMemo<GridState>(() => {
return {
rowSelection: ["2"],
};
}, []);
const { data, loading } = useFetchJson<IOlympicData>(
"https://www.ag-grid.com/example-assets/small-olympic-winners.json",
);
return (
<AgGridProvider modules={modules}>
<div style={containerStyle}>
<div style={gridStyle}>
<AgGridReact<IOlympicData>
rowData={data}
loading={loading}
columnDefs={columnDefs}
defaultColDef={defaultColDef}
rowSelection={rowSelection}
initialState={initialState}
/>
</div>
</div>
</AgGridProvider>
);
};
const root = createRoot(document.getElementById("root")!);
root.render(
<StrictMode>
<GridExample />
</StrictMode>,
);
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 rowNumbers = true;
const rowSelection = useMemo(() => {
return {
mode: 'singleRow',
checkboxes: false,
enableClickSelection: true,
};
}, []);
<AgGridReact
rowNumbers={rowNumbers}
rowSelection={rowSelection}
/>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 rowSelection = useMemo(() => {
return {
mode: 'singleRow',
isRowSelectable: (rowNode) => rowNode.data ? rowNode.data.year < 2007 : false,
hideDisabledCheckboxes: true
};
}, []);
<AgGridReact rowSelection={rowSelection} />Rows for which isRowSelectable returns false cannot be selected at all, whether using the UI or the API.
'use client';
import { useFetchJson } from './useFetchJson';
import React, { StrictMode, useMemo, useRef } from "react";
import { createRoot } from "react-dom/client";
import {
ClientSideRowModelModule,
RowSelectionModule,
enableDevValidations,
} from "ag-grid-community";
import type { ColDef, RowSelectionOptions } from "ag-grid-community";
import { AgGridProvider, AgGridReact } from "ag-grid-react";
import "./styles.css";
if (process.env.NODE_ENV !== "production") {
// Enable extended validations only for development
enableDevValidations();
}
const modules = [RowSelectionModule, ClientSideRowModelModule];
const GridExample = () => {
const grid = useRef<AgGridReact>(null);
const defaultColDef = useMemo(
() => ({
flex: 1,
minWidth: 100,
}),
[],
);
const columnDefs = useMemo<ColDef[]>(
() => [
{ field: "year", maxWidth: 120 },
{ field: "athlete" },
{ field: "sport" },
],
[],
);
const rowSelection = useMemo<RowSelectionOptions>(
() => ({
mode: "singleRow",
hideDisabledCheckboxes: true,
isRowSelectable: (node) => (node.data ? node.data.year < 2007 : false),
}),
[],
);
const { data, loading } = useFetchJson<IOlympicData>(
"https://www.ag-grid.com/example-assets/small-olympic-winners.json",
);
function toggleHideCheckbox() {
grid.current?.api.setGridOption("rowSelection", {
mode: "singleRow",
isRowSelectable: (node) => (node.data ? node.data.year < 2007 : false),
hideDisabledCheckboxes: getCheckboxValue("#toggle-hide-checkbox"),
});
}
return (
<AgGridProvider modules={modules}>
<div className="example-wrapper">
<div className="example-header">
<label>
<span>Hide disabled checkboxes:</span>
<input
id="toggle-hide-checkbox"
type="checkbox"
defaultChecked
onChange={toggleHideCheckbox}
/>
</label>
</div>
<div id="myGrid" className="grid">
<AgGridReact
ref={grid}
rowData={data}
loading={loading}
defaultColDef={defaultColDef}
columnDefs={columnDefs}
rowSelection={rowSelection}
/>
</div>
</div>
</AgGridProvider>
);
};
const root = createRoot(document.getElementById("root")!);
root.render(
<StrictMode>
<GridExample />
</StrictMode>,
);
function getCheckboxValue(id: string): boolean {
return document.querySelector<HTMLInputElement>(id)?.checked ?? false;
}
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.
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 selectionColumnDef = useMemo(() => {
return {
sortable: true,
resizable: true,
width: 100,
suppressHeaderMenuButton: false,
headerTooltip: 'Checkboxes indicate selection',
};
}, []);
<AgGridReact selectionColumnDef={selectionColumnDef} />"use client";
import React, {
useCallback,
useMemo,
useRef,
useState,
StrictMode,
} from "react";
import { createRoot } from "react-dom/client";
import { AgGridReact, AgGridProvider } from "ag-grid-react";
import {
ClientSideRowModelModule,
ColDef,
ColGroupDef,
GridApi,
GridOptions,
ModuleRegistry,
RowSelectionModule,
RowSelectionOptions,
SelectionColumnDef,
TooltipModule,
enableDevValidations,
} from "ag-grid-community";
import {
ColumnMenuModule,
ColumnsToolPanelModule,
ContextMenuModule,
RowGroupingModule,
} from "ag-grid-enterprise";
import { IOlympicData } from "./interfaces";
import { useFetchJson } from "./useFetchJson";
if (process.env.NODE_ENV !== "production") {
// Enable extended validations only for development
enableDevValidations();
}
const modules = [
RowSelectionModule,
TooltipModule,
ClientSideRowModelModule,
ColumnsToolPanelModule,
ColumnMenuModule,
ContextMenuModule,
RowGroupingModule,
];
const GridExample = () => {
const containerStyle = useMemo(() => ({ width: "100%", height: "100%" }), []);
const gridStyle = useMemo(() => ({ height: "100%", width: "100%" }), []);
const [columnDefs, setColumnDefs] = useState<ColDef[]>([
{ field: "athlete" },
{ field: "sport" },
{ field: "year", maxWidth: 120 },
]);
const defaultColDef = useMemo<ColDef>(() => {
return {
flex: 1,
minWidth: 100,
};
}, []);
const rowSelection = useMemo<
RowSelectionOptions | "single" | "multiple"
>(() => {
return { mode: "singleRow" };
}, []);
const selectionColumnDef = useMemo<SelectionColumnDef>(() => {
return {
sortable: true,
resizable: true,
width: 100,
suppressHeaderMenuButton: false,
headerTooltip: "Checkboxes indicate selection",
};
}, []);
const { data, loading } = useFetchJson<IOlympicData>(
"https://www.ag-grid.com/example-assets/small-olympic-winners.json",
);
return (
<AgGridProvider modules={modules}>
<div style={containerStyle}>
<div style={gridStyle}>
<AgGridReact<IOlympicData>
rowData={data}
loading={loading}
columnDefs={columnDefs}
defaultColDef={defaultColDef}
rowSelection={rowSelection}
selectionColumnDef={selectionColumnDef}
/>
</div>
</div>
</AgGridProvider>
);
};
const root = createRoot(document.getElementById("root")!);
root.render(
<StrictMode>
<GridExample />
</StrictMode>,
);
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.
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 rowSelection = useMemo(() => {
return {
mode: 'singleRow',
enableClickSelection: true,
};
}, []);
<AgGridReact rowSelection={rowSelection} />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.
"use client";
import React, {
useCallback,
useMemo,
useRef,
useState,
StrictMode,
} from "react";
import { createRoot } from "react-dom/client";
import { AgGridReact, AgGridProvider } from "ag-grid-react";
import {
ClientSideRowModelModule,
ColDef,
ColGroupDef,
GridApi,
GridOptions,
ModuleRegistry,
RowSelectionModule,
RowSelectionOptions,
enableDevValidations,
} from "ag-grid-community";
import {
ColumnMenuModule,
ColumnsToolPanelModule,
ContextMenuModule,
RowGroupingModule,
} from "ag-grid-enterprise";
import "./styles.css";
import { IOlympicData } from "./interfaces";
import { useFetchJson } from "./useFetchJson";
if (process.env.NODE_ENV !== "production") {
// Enable extended validations only for development
enableDevValidations();
}
const modules = [
RowSelectionModule,
ClientSideRowModelModule,
ColumnsToolPanelModule,
ColumnMenuModule,
ContextMenuModule,
RowGroupingModule,
];
const GridExample = () => {
const gridRef = useRef<AgGridReact<IOlympicData>>(null);
const containerStyle = useMemo(() => ({ width: "100%", height: "100%" }), []);
const gridStyle = useMemo(() => ({ height: "100%", width: "100%" }), []);
const [columnDefs, setColumnDefs] = useState<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 = useMemo<ColDef>(() => {
return {
flex: 1,
minWidth: 100,
};
}, []);
const rowSelection = useMemo<
RowSelectionOptions | "single" | "multiple"
>(() => {
return {
mode: "singleRow",
enableClickSelection: true,
};
}, []);
const { data, loading } = useFetchJson<IOlympicData>(
"https://www.ag-grid.com/example-assets/small-olympic-winners.json",
);
const onEnableClickSelection = useCallback(() => {
const value =
document.querySelector<HTMLSelectElement>("#select-enable")?.value;
gridRef.current!.api.setGridOption("rowSelection", {
mode: "singleRow",
enableClickSelection:
value === "true" ? true : value === "false" ? false : (value as any),
});
}, []);
return (
<AgGridProvider modules={modules}>
<div style={containerStyle}>
<div className="example-wrapper">
<div className="example-header">
<label>
<span>Enable Click Selection: </span>
<select id="select-enable" onChange={onEnableClickSelection}>
<option value="true">true</option>
<option value="enableSelection">enableSelection</option>
<option value="enableDeselection">enableDeselection</option>
<option value="false">false</option>
</select>
</label>
</div>
<div style={gridStyle}>
<AgGridReact<IOlympicData>
ref={gridRef}
rowData={data}
loading={loading}
columnDefs={columnDefs}
defaultColDef={defaultColDef}
rowSelection={rowSelection}
/>
</div>
</div>
</div>
</AgGridProvider>
);
};
const root = createRoot(document.getElementById("root")!);
root.render(
<StrictMode>
<GridExample />
</StrictMode>,
);
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' |
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. |
Set to true or return true from the callback to render a selection checkbox. |
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. |
Set to true to hide a disabled checkbox when row is not selectable and checkboxes are enabled. |
Callback to be used to determine which rows are selectable. By default rows are selectable, so return false to make a row non-selectable.
|
When enabled and a row is selected, the copy action should copy the entire row, rather than just the focused cell |
Set to true to allow (possibly multiple) rows to be selected and deselected using single click or touch. |
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. |