Row selection
Added in Handsontable 19.0.0Let 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 callupdateData()when you pass newdata, so the selection survives an update that replaces the array. To start over, calldeselectAll(). 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.
import { useRef, useState } from 'react';import { HotTable } from '@handsontable/react-wrapper';import { registerAllModules } from 'handsontable/registry';
// register Handsontable's modulesregisterAllModules();
const 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'],];
const ExampleComponent = () => { const hotRef = useRef(null); const [output, setOutput] = useState('Selected products: none');
return ( <> <HotTable // licenseKey="your-license-key" // get a key at https://handsontable.com/pricing/ ref={hotRef} data={data} 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', }} afterRowSelectionChange={() => { const selected = hotRef.current?.hotInstance?.getPlugin('rowSelection').getSelectedRowsData() ?? [];
setOutput(`Selected products: ${selected.map((row) => row[0]).join(', ') || 'none'}`); }} autoWrapRow={true} autoWrapCol={true} /> <output className="console">{output}</output> </> );};
export default ExampleComponent;import { useRef, useState } from 'react';import { HotTable, HotTableRef } from '@handsontable/react-wrapper';import { registerAllModules } from 'handsontable/registry';
// register Handsontable's modulesregisterAllModules();
const 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'],];
const ExampleComponent = () => { const hotRef = useRef<HotTableRef>(null); const [output, setOutput] = useState('Selected products: none');
return ( <> <HotTable // licenseKey="your-license-key" // get a key at https://handsontable.com/pricing/ ref={hotRef} data={data} 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', }} afterRowSelectionChange={() => { const selected = hotRef.current?.hotInstance?.getPlugin('rowSelection').getSelectedRowsData() as string[][] | undefined ?? [];
setOutput(`Selected products: ${selected.map((row) => row[0]).join(', ') || 'none'}`); }} autoWrapRow={true} autoWrapCol={true} /> <output className="console">{output}</output> </> );};
export default ExampleComponent;Choose where the checkboxes go
The checkboxLocation option, together with the rowHeaders option, gives you four layouts:
| Layout | checkboxLocation | rowHeaders | Where the “select all” checkbox goes |
|---|---|---|---|
| Next to the row numbers | 'rowHeader' (default) | true | The corner above the checkboxes |
| Without row numbers | 'rowHeader' (default) | false | The corner above the checkboxes |
| In the first column | 'firstColumn' | false | The first column’s header |
| In a checkbox column of your data | { column } | any | That 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.
import { HotTable } from '@handsontable/react-wrapper';import { registerAllModules } from 'handsontable/registry';
// register Handsontable's modulesregisterAllModules();
const 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'],];
const ExampleComponent = () => { return ( <HotTable // licenseKey="your-license-key" // get a key at https://handsontable.com/pricing/ data={data} 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} /> );};
export default ExampleComponent;import { HotTable } from '@handsontable/react-wrapper';import { registerAllModules } from 'handsontable/registry';
// register Handsontable's modulesregisterAllModules();
const 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'],];
const ExampleComponent = () => { return ( <HotTable // licenseKey="your-license-key" // get a key at https://handsontable.com/pricing/ data={data} 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} /> );};
export default ExampleComponent;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.
import { HotTable } from '@handsontable/react-wrapper';import { registerAllModules } from 'handsontable/registry';
// register Handsontable's modulesregisterAllModules();
const 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' },];
const ExampleComponent = () => { return ( <HotTable // licenseKey="your-license-key" // get a key at https://handsontable.com/pricing/ data={data} 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} /> );};
export default ExampleComponent;import { HotTable } from '@handsontable/react-wrapper';import { registerAllModules } from 'handsontable/registry';
// register Handsontable's modulesregisterAllModules();
const 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' },];
const ExampleComponent = () => { return ( <HotTable // licenseKey="your-license-key" // get a key at https://handsontable.com/pricing/ data={data} 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} /> );};
export default ExampleComponent;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
afterChangeand undo and redo, and a server-backed grid saves it. - Changes that come from edits, such as a paste, also reach the
beforeRowSelectionChangehook. Returnfalseto cancel them. - A read-only cell can’t be selected.
- When
isRowSelectablereturnsfalsefor a row, checking its cell doesn’t select it — the edit is canceled. Unchecking the cell still works.
import { HotTable } from '@handsontable/react-wrapper';import { registerAllModules } from 'handsontable/registry';
// register Handsontable's modulesregisterAllModules();
const 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 },];
const ExampleComponent = () => { return ( <HotTable // licenseKey="your-license-key" // get a key at https://handsontable.com/pricing/ data={data} 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} /> );};
export default ExampleComponent;import { HotTable } from '@handsontable/react-wrapper';import { registerAllModules } from 'handsontable/registry';
// register Handsontable's modulesregisterAllModules();
const 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 },];
const ExampleComponent = () => { return ( <HotTable // licenseKey="your-license-key" // get a key at https://handsontable.com/pricing/ data={data} 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} /> );};
export default ExampleComponent;Configuration options
| Option | Possible settings | Default | Description |
|---|---|---|---|
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. |
checkboxes | true | false | a function | true | Shows 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. |
headerCheckbox | true | false | true | Shows 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. |
enableClickSelection | false | true | 'enableSelection' | 'enableDeselection' | false | Lets a click on a cell select its row. |
isRowSelectable | A function | - | (rowData, physicalRow) => boolean. A row that returns false can’t be selected. |
hideDisabledCheckboxes | true | false | false | Hides 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:
| Setting | Rows 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.
import { useEffect, useRef } from 'react';import { HotTable } from '@handsontable/react-wrapper';import { registerAllModules } from 'handsontable/registry';
// register Handsontable's modulesregisterAllModules();
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 ExampleComponent = () => { const hotRef = useRef(null);
useEffect(() => { // preselect the Wireless Mouse and the Desk Lamp to show the mixed parents hotRef.current?.hotInstance?.getPlugin('rowSelection').selectRows([5, 13]); }, []);
return ( <HotTable // licenseKey="your-license-key" // get a key at https://handsontable.com/pricing/ ref={hotRef} data={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} /> );};
export default ExampleComponent;import { useEffect, useRef } from 'react';import { HotTable, HotTableRef } from '@handsontable/react-wrapper';import { registerAllModules } from 'handsontable/registry';
// register Handsontable's modulesregisterAllModules();
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 ExampleComponent = () => { const hotRef = useRef<HotTableRef>(null);
useEffect(() => { // preselect the Wireless Mouse and the Desk Lamp to show the mixed parents hotRef.current?.hotInstance?.getPlugin('rowSelection').selectRows([5, 13]); }, []);
return ( <HotTable // licenseKey="your-license-key" // get a key at https://handsontable.com/pricing/ ref={hotRef} data={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} /> );};
export default ExampleComponent;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
afterRowSelectionChangehook lists the leaves that change.getSelectedRows()also lists the parents whose leaves are all selected.getSelectedCount()counts the leaves only. - When
isRowSelectablereturnsfalsefor a parent row, the rows under it can’t be selected either.
To change these rules, set the groupSelects option:
| Setting | Behavior |
|---|---|
'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 outrowSelection.getSelectedRows();
// source data of every selected row, including the filtered-out onesrowSelection.getSelectedRowsData();
// select rows by their visual indexesrowSelection.selectRows([0, 2]);
// select every row in scope, or clear the whole selectionrowSelection.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.
nis 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 whenallowRemoveRowisfalse. - Clear row selection deselects every row.
Both items are hidden while no row is selected.
Keyboard shortcuts
| Windows | macOS | Action |
|---|---|---|
| Space | Space | On 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. |
| Space | Space | On a row checkbox: toggle the row. On the “select all” checkbox: toggle every row in scope. |
| Shift+click | Shift+click | Select 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 theDataProviderplugin, the selection survives page changes — see Server-side row selection. - With
checkboxLocation: 'firstColumn', the plugin widens the first column for the checkbox only when theAutoColumnSizeplugin sets its width.
Related API reference
Configuration options
Hooks
Plugins