Skip to content

Row selection

Added in Handsontable 19.0.0

Let users select rows with checkboxes, and select or clear every row at once with a “select all” checkbox.

Overview

The RowSelection plugin adds a checkbox to every row and a “select all” checkbox above them.

The row selection is separate from the cell selection:

  • Selecting a row doesn’t select its cells, and selecting cells doesn’t select rows.
  • By default, the plugin doesn’t write anything into your data. To keep the selection in your data, see In a checkbox column of your data.
  • The selection follows its rows when you sort, filter, move, add, or remove rows.
  • loadData() clears the selection. updateData() keeps it by row position: the row at each selected position stays selected, whatever record the new data puts there. The React, Angular, and Vue wrappers call updateData() when you pass new data, so the selection survives an update that replaces the array. To start over, call deselectAll(). A selection kept in a checkbox column of your data is read from the new data instead.

Enable row selection

To enable row selection, set the rowSelection option to true, or to an object with your configuration.

In the following example:

  • Discontinued products can’t be selected, so their checkboxes are disabled.
  • The “select all” checkbox acts on the rows that pass the filters. Filter the Category column, and then select all rows.
  • The line under the grid lists the selected products.
Selected products: none
JavaScript
import Handsontable from 'handsontable/base';
import { registerAllModules } from 'handsontable/registry';
// Register all Handsontable's modules.
registerAllModules();
const container = document.querySelector('#example1');
const output = document.querySelector('#example1-output');
const hot = new Handsontable(container, {
// licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/
data: [
['SKU-4821', 'Stainless Steel Water Bottle', 'Harbor Goods', 'Drinkware', 'Active'],
['SKU-0093', 'Wireless Mouse', 'Alpine Supply Co.', 'Electronics', 'Active'],
['SKU-1170', 'Ergonomic Office Chair', 'Cascade Distributors', 'Furniture', 'Discontinued'],
['SKU-2208', 'USB-C Charging Cable', 'Summit Trading', 'Electronics', 'Active'],
['SKU-3341', 'Aluminum Water Filter', 'Northgate Wholesale', 'Drinkware', 'Active'],
['SKU-4412', 'Canvas Tote Bag', 'Nordic Traders', 'Apparel', 'Discontinued'],
['SKU-5088', 'USB-C Hub', 'Harbor Goods', 'Electronics', 'Active'],
['SKU-6120', 'Ceramic Mug Set', 'Alpine Supply Co.', 'Drinkware', 'Active'],
['SKU-7294', 'Desk Lamp', 'Cascade Distributors', 'Furniture', 'Active'],
['SKU-8015', 'Laptop Stand', 'Summit Trading', 'Furniture', 'Active'],
],
height: 'auto',
colHeaders: ['SKU', 'Product', 'Supplier', 'Category', 'Status'],
rowHeaders: true,
// reach the header checkboxes with the arrow keys, toggle them with Space
navigableHeaders: true,
filters: true,
dropdownMenu: true,
// enable the `RowSelection` plugin
rowSelection: {
// "select all" acts on the rows that pass the filters
selectAll: 'filtered',
// discontinued products can't be selected
isRowSelectable: (rowData) => rowData[4] !== 'Discontinued',
},
autoWrapRow: true,
autoWrapCol: true,
afterRowSelectionChange() {
const selected = hot.getPlugin('rowSelection').getSelectedRowsData();
output.innerText = `Selected products: ${selected.map((row) => row[0]).join(', ') || 'none'}`;
},
});
TypeScript
import Handsontable from 'handsontable/base';
import { registerAllModules } from 'handsontable/registry';
// Register all Handsontable's modules.
registerAllModules();
const container = document.querySelector('#example1')!;
const output = document.querySelector<HTMLOutputElement>('#example1-output')!;
const hot = new Handsontable(container, {
// licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/
data: [
['SKU-4821', 'Stainless Steel Water Bottle', 'Harbor Goods', 'Drinkware', 'Active'],
['SKU-0093', 'Wireless Mouse', 'Alpine Supply Co.', 'Electronics', 'Active'],
['SKU-1170', 'Ergonomic Office Chair', 'Cascade Distributors', 'Furniture', 'Discontinued'],
['SKU-2208', 'USB-C Charging Cable', 'Summit Trading', 'Electronics', 'Active'],
['SKU-3341', 'Aluminum Water Filter', 'Northgate Wholesale', 'Drinkware', 'Active'],
['SKU-4412', 'Canvas Tote Bag', 'Nordic Traders', 'Apparel', 'Discontinued'],
['SKU-5088', 'USB-C Hub', 'Harbor Goods', 'Electronics', 'Active'],
['SKU-6120', 'Ceramic Mug Set', 'Alpine Supply Co.', 'Drinkware', 'Active'],
['SKU-7294', 'Desk Lamp', 'Cascade Distributors', 'Furniture', 'Active'],
['SKU-8015', 'Laptop Stand', 'Summit Trading', 'Furniture', 'Active'],
],
height: 'auto',
colHeaders: ['SKU', 'Product', 'Supplier', 'Category', 'Status'],
rowHeaders: true,
// reach the header checkboxes with the arrow keys, toggle them with Space
navigableHeaders: true,
filters: true,
dropdownMenu: true,
// enable the `RowSelection` plugin
rowSelection: {
// "select all" acts on the rows that pass the filters
selectAll: 'filtered',
// discontinued products can't be selected
isRowSelectable: (rowData: unknown) => (rowData as string[])[4] !== 'Discontinued',
},
autoWrapRow: true,
autoWrapCol: true,
afterRowSelectionChange() {
const selected = hot.getPlugin('rowSelection').getSelectedRowsData();
output.innerText = `Selected products: ${(selected as string[][]).map((row) => row[0]).join(', ') || 'none'}`;
},
});
HTML
<div id="example1"></div>
<output class="console" id="example1-output">Selected products: none</output>

Choose where the checkboxes go

The checkboxLocation option, together with the rowHeaders option, gives you four layouts:

LayoutcheckboxLocationrowHeadersWhere the “select all” checkbox goes
Next to the row numbers'rowHeader' (default)trueThe corner above the checkboxes
Without row numbers'rowHeader' (default)falseThe corner above the checkboxes
In the first column'firstColumn'falseThe first column’s header
In a checkbox column of your data{ column }anyThat column’s header

The first three layouts keep the selection apart from your data. The last one stores it in your data.

Next to the row numbers

This is the default. The checkboxes get a narrow row header column of their own, between the row numbers and the data. The example at the top of this page uses this layout.

Without row numbers

Set rowHeaders to false. The checkbox column stays, and it’s the only row header column.

JavaScript
import Handsontable from 'handsontable/base';
import { registerAllModules } from 'handsontable/registry';
// Register all Handsontable's modules.
registerAllModules();
const container = document.querySelector('#example2');
new Handsontable(container, {
// licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/
data: [
['SKU-4821', 'Stainless Steel Water Bottle', 'Harbor Goods', 'Drinkware'],
['SKU-0093', 'Wireless Mouse', 'Alpine Supply Co.', 'Electronics'],
['SKU-1170', 'Ergonomic Office Chair', 'Cascade Distributors', 'Furniture'],
['SKU-2208', 'USB-C Charging Cable', 'Summit Trading', 'Electronics'],
['SKU-3341', 'Aluminum Water Filter', 'Northgate Wholesale', 'Drinkware'],
['SKU-4412', 'Canvas Tote Bag', 'Nordic Traders', 'Apparel'],
],
height: 'auto',
colHeaders: ['SKU', 'Product', 'Supplier', 'Category'],
// no row numbers: the checkbox column is the only row header
rowHeaders: false,
// reach the header checkbox with the arrow keys, toggle it with Space
navigableHeaders: true,
rowSelection: true,
autoWrapRow: true,
autoWrapCol: true,
});
TypeScript
import Handsontable from 'handsontable/base';
import { registerAllModules } from 'handsontable/registry';
// Register all Handsontable's modules.
registerAllModules();
const container = document.querySelector('#example2')!;
new Handsontable(container, {
// licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/
data: [
['SKU-4821', 'Stainless Steel Water Bottle', 'Harbor Goods', 'Drinkware'],
['SKU-0093', 'Wireless Mouse', 'Alpine Supply Co.', 'Electronics'],
['SKU-1170', 'Ergonomic Office Chair', 'Cascade Distributors', 'Furniture'],
['SKU-2208', 'USB-C Charging Cable', 'Summit Trading', 'Electronics'],
['SKU-3341', 'Aluminum Water Filter', 'Northgate Wholesale', 'Drinkware'],
['SKU-4412', 'Canvas Tote Bag', 'Nordic Traders', 'Apparel'],
],
height: 'auto',
colHeaders: ['SKU', 'Product', 'Supplier', 'Category'],
// no row numbers: the checkbox column is the only row header
rowHeaders: false,
// reach the header checkbox with the arrow keys, toggle it with Space
navigableHeaders: true,
rowSelection: true,
autoWrapRow: true,
autoWrapCol: true,
});

In the first column

Set checkboxLocation to 'firstColumn' to render each checkbox inside the first visible column, before the cell’s value. The “select all” checkbox goes into that column’s header, before its label. The checkboxes follow the column when you move or hide columns.

To give the checkboxes a column of their own, as in the following example, make the first column an empty column with no label and editor: false. It doesn’t need a field in your data, and the checkbox is centered in it.

This layout fits a grid without row headers. With rowHeaders: true it works as well, and the row numbers stay.

Don’t render the checkboxes into a checkbox column: each cell would show two checkboxes. To use the values of a checkbox column as the selection, see In a checkbox column of your data.

JavaScript
import Handsontable from 'handsontable/base';
import { registerAllModules } from 'handsontable/registry';
// Register all Handsontable's modules.
registerAllModules();
const container = document.querySelector('#example3');
new Handsontable(container, {
// licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/
data: [
{ sku: 'SKU-4821', product: 'Stainless Steel Water Bottle', supplier: 'Harbor Goods', category: 'Drinkware' },
{ sku: 'SKU-0093', product: 'Wireless Mouse', supplier: 'Alpine Supply Co.', category: 'Electronics' },
{ sku: 'SKU-1170', product: 'Ergonomic Office Chair', supplier: 'Cascade Distributors', category: 'Furniture' },
{ sku: 'SKU-2208', product: 'USB-C Charging Cable', supplier: 'Summit Trading', category: 'Electronics' },
{ sku: 'SKU-3341', product: 'Aluminum Water Filter', supplier: 'Northgate Wholesale', category: 'Drinkware' },
{ sku: 'SKU-4412', product: 'Canvas Tote Bag', supplier: 'Nordic Traders', category: 'Apparel' },
],
columns: [
// an empty column that holds only the checkboxes, with no label and no editor
{ data: 'rowSelection', editor: false, width: 44, className: 'htCenter' },
{ data: 'sku' },
{ data: 'product' },
{ data: 'supplier' },
{ data: 'category' },
],
colHeaders: ['', 'SKU', 'Product', 'Supplier', 'Category'],
height: 'auto',
rowHeaders: false,
// reach the header checkbox with the arrow keys, toggle it with Space
navigableHeaders: true,
// render the checkboxes inside the first column
rowSelection: {
checkboxLocation: 'firstColumn',
},
autoWrapRow: true,
autoWrapCol: true,
});
TypeScript
import Handsontable from 'handsontable/base';
import { registerAllModules } from 'handsontable/registry';
// Register all Handsontable's modules.
registerAllModules();
const container = document.querySelector('#example3')!;
new Handsontable(container, {
// licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/
data: [
{ sku: 'SKU-4821', product: 'Stainless Steel Water Bottle', supplier: 'Harbor Goods', category: 'Drinkware' },
{ sku: 'SKU-0093', product: 'Wireless Mouse', supplier: 'Alpine Supply Co.', category: 'Electronics' },
{ sku: 'SKU-1170', product: 'Ergonomic Office Chair', supplier: 'Cascade Distributors', category: 'Furniture' },
{ sku: 'SKU-2208', product: 'USB-C Charging Cable', supplier: 'Summit Trading', category: 'Electronics' },
{ sku: 'SKU-3341', product: 'Aluminum Water Filter', supplier: 'Northgate Wholesale', category: 'Drinkware' },
{ sku: 'SKU-4412', product: 'Canvas Tote Bag', supplier: 'Nordic Traders', category: 'Apparel' },
],
columns: [
// an empty column that holds only the checkboxes, with no label and no editor
{ data: 'rowSelection', editor: false, width: 44, className: 'htCenter' },
{ data: 'sku' },
{ data: 'product' },
{ data: 'supplier' },
{ data: 'category' },
],
colHeaders: ['', 'SKU', 'Product', 'Supplier', 'Category'],
height: 'auto',
rowHeaders: false,
// reach the header checkbox with the arrow keys, toggle it with Space
navigableHeaders: true,
// render the checkboxes inside the first column
rowSelection: {
checkboxLocation: 'firstColumn',
},
autoWrapRow: true,
autoWrapCol: true,
});

In a checkbox column of your data

To keep the selection in your data, point checkboxLocation at a checkbox column. Use the column’s data property, or its index:

rowSelection: {
checkboxLocation: { column: 'selected' },
},

The column’s values are then the selection:

  • Checking a cell selects its row, and selecting a row checks its cell. Each row keeps a single checkbox.
  • The “select all” checkbox sits in that column’s header.
  • Every change is a data change. It goes through afterChange and undo and redo, and a server-backed grid saves it.
  • Changes that come from edits, such as a paste, also reach the beforeRowSelectionChange hook. Return false to cancel them.
  • A read-only cell can’t be selected.
  • When isRowSelectable returns false for a row, checking its cell doesn’t select it — the edit is canceled. Unchecking the cell still works.
JavaScript
import Handsontable from 'handsontable/base';
import { registerAllModules } from 'handsontable/registry';
// Register all Handsontable's modules.
registerAllModules();
const container = document.querySelector('#example4');
new Handsontable(container, {
// licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/
data: [
{ order: 1001, customer: 'Harbor Goods', total: 420, selected: false },
{ order: 1002, customer: 'Alpine Supply Co.', total: 185, selected: true },
{ order: 1003, customer: 'Cascade Distributors', total: 960, selected: false },
{ order: 1004, customer: 'Summit Trading', total: 75, selected: false },
{ order: 1005, customer: 'Nordic Traders', total: 310, selected: true },
{ order: 1006, customer: 'Northgate Wholesale', total: 540, selected: false },
],
columns: [
{ data: 'selected', title: 'Selected', type: 'checkbox' },
{ data: 'order', title: 'Order', readOnly: true },
{ data: 'customer', title: 'Customer' },
{ data: 'total', title: 'Total', type: 'numeric' },
],
colHeaders: true,
rowHeaders: true,
// reach the header checkboxes with the arrow keys, toggle them with Space
navigableHeaders: true,
height: 'auto',
// the values of the `selected` column are the row selection
rowSelection: {
checkboxLocation: { column: 'selected' },
},
autoWrapRow: true,
autoWrapCol: true,
});
TypeScript
import Handsontable from 'handsontable/base';
import { registerAllModules } from 'handsontable/registry';
// Register all Handsontable's modules.
registerAllModules();
const container = document.querySelector('#example4')!;
new Handsontable(container, {
// licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/
data: [
{ order: 1001, customer: 'Harbor Goods', total: 420, selected: false },
{ order: 1002, customer: 'Alpine Supply Co.', total: 185, selected: true },
{ order: 1003, customer: 'Cascade Distributors', total: 960, selected: false },
{ order: 1004, customer: 'Summit Trading', total: 75, selected: false },
{ order: 1005, customer: 'Nordic Traders', total: 310, selected: true },
{ order: 1006, customer: 'Northgate Wholesale', total: 540, selected: false },
],
columns: [
{ data: 'selected', title: 'Selected', type: 'checkbox' },
{ data: 'order', title: 'Order', readOnly: true },
{ data: 'customer', title: 'Customer' },
{ data: 'total', title: 'Total', type: 'numeric' },
],
colHeaders: true,
rowHeaders: true,
// reach the header checkboxes with the arrow keys, toggle them with Space
navigableHeaders: true,
height: 'auto',
// the values of the `selected` column are the row selection
rowSelection: {
checkboxLocation: { column: 'selected' },
},
autoWrapRow: true,
autoWrapCol: true,
});

Configuration options

OptionPossible settingsDefaultDescription
mode'multiRow' | 'singleRow''multiRow''singleRow' keeps at most one row selected and removes the “select all” checkbox. Switching to 'singleRow' with updateSettings() keeps only the last toggled row selected.
checkboxestrue | false | a functiontrueShows the row checkboxes. A function (rowData, physicalRow) => boolean decides per row. A row without a checkbox can’t be toggled from its row header, but Space on its data cells still toggles it.
headerCheckboxtrue | falsetrueShows the “select all” checkbox. With false, the corner works as a plain corner: a click on it selects every cell.
selectAll'all' | 'filtered' | 'currentPage''all'The rows the “select all” checkbox acts on. See Choose what “select all” selects.
enableClickSelectionfalse | true | 'enableSelection' | 'enableDeselection'falseLets a click on a cell select its row.
isRowSelectableA function-(rowData, physicalRow) => boolean. A row that returns false can’t be selected.
hideDisabledCheckboxestrue | falsefalseHides the checkboxes of rows that can’t be selected, instead of disabling them.
checkboxLocation'rowHeader' | 'firstColumn' | { column }'rowHeader'Renders the checkboxes in an extra row header column or in the first visible column, or uses a checkbox column as the selection. See Choose where the checkboxes go.
groupSelects'descendants' | 'self' | 'topLevel''descendants'How the rows of a nested rows tree are selected. See Select rows with nested rows.

Choose what “select all” selects

The “select all” checkbox always describes the rows that a click on it acts on:

  • When none of these rows is selected, the checkbox is unchecked.
  • When all of them are selected, the checkbox is checked.
  • When only some are selected, the checkbox shows a mixed state, and a click selects all of them.

The selectAll option sets which rows count:

SettingRows in scope
'all' (default)Every row of the dataset, including the rows that the filters hide.
'filtered'The rows that pass the filters, on every page.
'currentPage'The rows on the current page.

Rows hidden with the HiddenRows plugin and rows trimmed with the TrimRows plugin are never in scope. With the NestedRows plugin, see Select rows with nested rows for which rows count.

Select rows with nested rows

With the NestedRows plugin, every level of the tree gets a checkbox. Selecting a parent row selects every row under it, at every depth. A parent shows a mixed state while only some of the rows under it are selected, so you can see on each level where the selected rows are. In the following example, the selected Wireless Mouse puts its subcategory and its category in the mixed state, and the Desk Lamp, the only product in Lighting, checks Lighting as well.

JavaScript
import Handsontable from 'handsontable/base';
import { registerAllModules } from 'handsontable/registry';
// Register all Handsontable's modules.
registerAllModules();
const data = [
{
name: 'Electronics',
sku: null,
stock: null,
__children: [
{
name: 'Audio',
sku: null,
stock: null,
__children: [
{ name: 'Wireless Headphones', sku: 'SKU-2001', stock: 34 },
{ name: 'Bluetooth Speaker', sku: 'SKU-2002', stock: 12 },
],
},
{
name: 'Computer Accessories',
sku: null,
stock: null,
__children: [
{ name: 'Wireless Mouse', sku: 'SKU-0093', stock: 120 },
{ name: 'USB-C Charging Cable', sku: 'SKU-2208', stock: 310 },
{ name: 'Laptop Stand', sku: 'SKU-3105', stock: 0 },
],
},
],
},
{
name: 'Home & Office',
sku: null,
stock: null,
__children: [
{
name: 'Furniture',
sku: null,
stock: null,
__children: [
{ name: 'Ergonomic Office Chair', sku: 'SKU-1170', stock: 8 },
{ name: 'Standing Desk', sku: 'SKU-1185', stock: 5 },
],
},
{
name: 'Lighting',
sku: null,
stock: null,
__children: [{ name: 'Desk Lamp', sku: 'SKU-1402', stock: 46 }],
},
],
},
{
name: 'Drinkware',
sku: null,
stock: null,
__children: [
{ name: 'Stainless Steel Water Bottle', sku: 'SKU-4821', stock: 75 },
{ name: 'Aluminum Water Filter', sku: 'SKU-3341', stock: 22 },
],
},
];
const container = document.querySelector('#example5');
const hot = new Handsontable(container, {
// licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/
data,
height: 'auto',
width: '100%',
stretchH: 'all',
colHeaders: ['Name', 'SKU', 'Stock'],
columns: [{ data: 'name' }, { data: 'sku' }, { data: 'stock', type: 'numeric' }],
// the collapse buttons live in the row headers
rowHeaders: true,
nestedRows: true,
// the default `groupSelects: 'descendants'`: a parent row selects every row under it,
// and shows a mixed state while only some of them are selected
rowSelection: true,
navigableHeaders: true,
autoWrapRow: true,
autoWrapCol: true,
});
// preselect the Wireless Mouse and the Desk Lamp to show the mixed parents
hot.getPlugin('rowSelection').selectRows([5, 13]);
TypeScript
import Handsontable from 'handsontable/base';
import { registerAllModules } from 'handsontable/registry';
// Register all Handsontable's modules.
registerAllModules();
interface CatalogRow {
name: string;
sku: string | null;
stock: number | null;
__children?: CatalogRow[];
}
const data: CatalogRow[] = [
{
name: 'Electronics',
sku: null,
stock: null,
__children: [
{
name: 'Audio',
sku: null,
stock: null,
__children: [
{ name: 'Wireless Headphones', sku: 'SKU-2001', stock: 34 },
{ name: 'Bluetooth Speaker', sku: 'SKU-2002', stock: 12 },
],
},
{
name: 'Computer Accessories',
sku: null,
stock: null,
__children: [
{ name: 'Wireless Mouse', sku: 'SKU-0093', stock: 120 },
{ name: 'USB-C Charging Cable', sku: 'SKU-2208', stock: 310 },
{ name: 'Laptop Stand', sku: 'SKU-3105', stock: 0 },
],
},
],
},
{
name: 'Home & Office',
sku: null,
stock: null,
__children: [
{
name: 'Furniture',
sku: null,
stock: null,
__children: [
{ name: 'Ergonomic Office Chair', sku: 'SKU-1170', stock: 8 },
{ name: 'Standing Desk', sku: 'SKU-1185', stock: 5 },
],
},
{
name: 'Lighting',
sku: null,
stock: null,
__children: [
{ name: 'Desk Lamp', sku: 'SKU-1402', stock: 46 },
],
},
],
},
{
name: 'Drinkware',
sku: null,
stock: null,
__children: [
{ name: 'Stainless Steel Water Bottle', sku: 'SKU-4821', stock: 75 },
{ name: 'Aluminum Water Filter', sku: 'SKU-3341', stock: 22 },
],
},
];
const container = document.querySelector('#example5')!;
const hot = new Handsontable(container, {
// licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/
data,
height: 'auto',
width: '100%',
stretchH: 'all',
colHeaders: ['Name', 'SKU', 'Stock'],
columns: [
{ data: 'name' },
{ data: 'sku' },
{ data: 'stock', type: 'numeric' },
],
// the collapse buttons live in the row headers
rowHeaders: true,
nestedRows: true,
// the default `groupSelects: 'descendants'`: a parent row selects every row under it,
// and shows a mixed state while only some of them are selected
rowSelection: true,
navigableHeaders: true,
autoWrapRow: true,
autoWrapCol: true,
});
// preselect the Wireless Mouse and the Desk Lamp to show the mixed parents
hot.getPlugin('rowSelection').selectRows([5, 13]);

The selection lives on the rows with no children (the leaves). A parent row only shows the state of the leaves under it:

  • A click on an unchecked or mixed parent selects every leaf under it. A click on a checked parent clears them.
  • The “select all” checkbox counts the leaves, including the leaves of collapsed parents.
  • The afterRowSelectionChange hook lists the leaves that change. getSelectedRows() also lists the parents whose leaves are all selected. getSelectedCount() counts the leaves only.
  • When isRowSelectable returns false for a parent row, the rows under it can’t be selected either.

To change these rules, set the groupSelects option:

SettingBehavior
'descendants' (default)A parent row selects the rows under it and shows their state, as described above.
'self'Every row, at any level, is selected on its own. A parent doesn’t change the rows under it.
'topLevel'Only the top-level rows can be selected, for example whole orders rather than their line items.
rowSelection: {
groupSelects: 'topLevel',
},

The 'singleRow' mode and a checkbox column of your data use 'self' in place of 'descendants', because a single row or a checkbox cell can’t show a mixed state.

Read the selection

Use the plugin’s methods to read and change the selection:

const rowSelection = hot.getPlugin('rowSelection');
// visual indexes of the selected rows that are not filtered out
rowSelection.getSelectedRows();
// source data of every selected row, including the filtered-out ones
rowSelection.getSelectedRowsData();
// select rows by their visual indexes
rowSelection.selectRows([0, 2]);
// select every row in scope, or clear the whole selection
rowSelection.selectAll();
rowSelection.deselectAll();

To react to changes, use the afterRowSelectionChange hook. To stop a change, return false from the beforeRowSelectionChange hook. Both hooks receive the physical indexes of the rows that change, and the source of the change ('checkbox', 'headerCheckbox', 'click', 'keyboard', 'api', or 'dataChange'). The 'dataChange' source means a write to a checkbox column of your data that didn’t come from editing the cell, for example a paste, an autofill, or a setDataAtCell() call.

Act on the selected rows from the context menu

With the ContextMenu plugin enabled, the default context menu gets two items while at least one row is selected:

  • Remove selected rows (n) removes the selected rows that the grid shows. n is the number of rows it removes: selected rows that the filters hide are kept, and the count leaves them out. The item is disabled when no shown row is selected, or when allowRemoveRow is false.
  • Clear row selection deselects every row.

Both items are hidden while no row is selected.

Keyboard shortcuts

WindowsmacOSAction
SpaceSpaceOn a data cell: toggle the cell’s row. With a range of cells selected: select every row of the range, or deselect them when all are already selected.
SpaceSpaceOn a row checkbox: toggle the row. On the “select all” checkbox: toggle every row in scope.
Shift+clickShift+clickSelect every row from the last toggled row to the clicked row. Rows hidden with the HiddenRows plugin or trimmed with the TrimRows plugin are skipped. With pagination, the rows on the pages between the two rows are selected too.

To reach the checkboxes with the arrow keys, enable the navigableHeaders option, as the examples on this page do. Without it, use Space on a data cell.

Space on a checkbox cell keeps checking the cell. Shift+Space and Ctrl+Space keep selecting a row and a column of cells. With row selection enabled, Space doesn’t start editing a cell — use Enter or F2.

Each change made with the mouse or the keyboard is announced to screen readers, for example “Row 3 selected” or “12 of 40 rows selected”.

Known limitations

  • Loading new data with loadData() clears the selection. With the DataProvider plugin, the selection survives page changes — see Server-side row selection.
  • With checkboxLocation: 'firstColumn', the plugin widens the first column for the checkbox only when the AutoColumnSize plugin sets its width.

Configuration options

Hooks

Plugins