RowSelection
See the Row selection guide for examples and configuration details.
Options
rowSelection
Can be set at: grid
rowSelection.rowSelection : boolean | object
The rowSelection option configures the RowSelection plugin, which
lets the user select rows with checkboxes, including a “select all” checkbox.
The row selection is a state of its own. It is not the cell selection, and the plugin never writes it into the data.
You can set the rowSelection option to one of the following:
| Setting | Description |
|---|---|
false | Disable the RowSelection plugin |
true | Enable the RowSelection plugin with its defaults |
| An object | Enable the plugin and configure it |
If you set the rowSelection option to an object, you can configure the following options:
| Option | Possible settings | Default |
|---|---|---|
mode | 'multiRow' | 'singleRow' | 'multiRow' |
checkboxes | A boolean, or a function (rowData, physicalRow) => boolean | true |
headerCheckbox | A boolean | true |
selectAll | 'all' | 'filtered' | 'currentPage' | 'all' |
enableClickSelection | true | false | 'enableSelection' | 'enableDeselection' | false |
isRowSelectable | A function (rowData, physicalRow) => boolean | - |
hideDisabledCheckboxes | A boolean | false |
checkboxLocation | 'rowHeader' | 'firstColumn' | { column } | 'rowHeader' |
groupSelects | 'descendants' | 'self' | 'topLevel' | 'descendants' |
With the NestedRows plugin, groupSelects sets how the rows of the tree are
selected. With 'descendants', selecting a parent row selects every row under it, and a parent shows a
mixed state while only some of the rows under it are selected. With 'self', every row is selected on its
own. With 'topLevel', only the top-level rows can be selected. The 'singleRow' mode and a bound
checkbox column (checkboxLocation: { column }) use 'self' in place of 'descendants'.
With checkboxLocation: { column: 'selected' }, the values of a checkbox column (its data property,
or its physical index) are the selection: selecting a row checks its cell, and checking a cell
selects its row.
Read more:
This option can only be set at the grid level.
It has no effect when set in the columns, cells, or cell options.
Default: undefined
Since: 19.0.0
Example
// enable the `RowSelection` plugin with its defaultsrowSelection: true,
// "select all" acts on the filtered rows, and archived rows cannot be selectedrowSelection: { selectAll: 'filtered', isRowSelectable: (rowData) => rowData.status !== 'archived',},Members
DEFAULT_SETTINGS
RowSelection.DEFAULT_SETTINGS
Returns the default settings applied when the plugin is enabled without explicit configuration.
LICENSE
RowSelection.LICENSE
Returns the license token of the plugin, its display name, where it is checked, and the tokens it requires.
PLUGIN_KEY
RowSelection.PLUGIN_KEY
Returns the plugin key used to identify this plugin in Handsontable settings.
PLUGIN_PRIORITY
RowSelection.PLUGIN_PRIORITY
Returns the priority order used to determine the order in which plugins are initialized.
SETTINGS_VALIDATORS
RowSelection.SETTINGS_VALIDATORS
Returns the validators the plugin settings are checked against.
Methods
deselectAll
rowSelection.deselectAll([scope]) ⇒ boolean
Deselects every row in the scope.
| Param | Type | Default | Description |
|---|---|---|---|
| [scope] | string | ”all” | optional 'all', 'filtered', or 'currentPage'. Defaults to 'all', so that a call clears the whole selection, rows filtered out included. |
Returns: boolean - true if the selection changed.
deselectRows
rowSelection.deselectRows(rows) ⇒ boolean
Deselects the rows.
| Param | Type | Description |
|---|---|---|
| rows | Array<number> | Visual row indexes. |
Returns: boolean - true if the selection changed.
destroy
rowSelection.destroy()
Destroys the plugin instance.
disablePlugin
rowSelection.disablePlugin()
Disables the plugin functionality for this Handsontable instance.
enablePlugin
rowSelection.enablePlugin()
Enables the plugin functionality for this Handsontable instance.
getBoundColumn
rowSelection.getBoundColumn() ⇒ number | null
Returns the visual index of the checkbox column whose values are the selection
(checkboxLocation: { column }), or null when the selection is not bound to a column.
getHeaderCheckboxState
rowSelection.getHeaderCheckboxState() ⇒ Object
Returns the state of the “select all” checkbox: 'checked', 'unchecked', 'mixed', or
'disabled' (no row in the scope can be selected), with the number of selected and selectable
rows in the scope.
getSelectedCount
rowSelection.getSelectedCount() ⇒ number
Returns the number of selected rows. With a server-backed grid (the
DataProvider plugin) and a “select all” scope other than
'currentPage', it counts the rows matching the server query, including the rows on other pages.
getSelectedPhysicalRows
rowSelection.getSelectedPhysicalRows() ⇒ Array<number>
Returns the physical indexes of the selected rows, including the rows the
Filters plugin filtered out.
getSelectedRows
rowSelection.getSelectedRows() ⇒ Array<number>
Returns the visual indexes of the selected rows, in visual order. Selected rows the
Filters plugin filtered out have no visual index and are not listed - use
RowSelection#getSelectedPhysicalRows or RowSelection#getSelectedRowsData for them.
getSelectedRowsData
rowSelection.getSelectedRowsData() ⇒ Array
Returns the source data of the selected rows, in physical order, including the rows the
Filters plugin filtered out. With a server-backed grid (the
DataProvider plugin), only the loaded rows have data: use
RowSelection#getServerSelection for the rest.
getServerSelection
rowSelection.getServerSelection() ⇒ Object | null
Returns the selection of a server-backed grid (the DataProvider
plugin) in a form your server can apply to the rows it did not send: selectAll: false with the
ids of the selected rows, or selectAll: true with the ids of the rows deselected after “select
all”. The ids come from the dataProvider.rowId option. Returns null without a server-backed grid.
isEnabled
rowSelection.isEnabled() ⇒ boolean
Checks if the plugin is enabled in the handsontable settings. This method is executed in Hooks#beforeInit
hook and if it returns true then the RowSelection#enablePlugin method is called.
isRowSelectable
rowSelection.isRowSelectable(row) ⇒ boolean
Checks whether the row can be selected. A row cannot be selected when the isRowSelectable
function returns false for it or for a parent above it, when it is a nested row and
groupSelects is 'topLevel', when it is a parent with no selectable row under it
(groupSelects: 'descendants'), or when its cell in a bound checkbox column is read-only.
| Param | Type | Description |
|---|---|---|
| row | number | Visual row index. |
isRowSelected
rowSelection.isRowSelected(row) ⇒ boolean
Checks whether the row is selected.
| Param | Type | Description |
|---|---|---|
| row | number | Visual row index. |
removeSelectedRows
rowSelection.removeSelectedRows() ⇒ boolean
Removes the selected rows from the grid, in one undo step. Only rows with a visual index are
removed: selected rows the Filters plugin filtered out stay. With a
server-backed grid after a “select all”, the rows on other pages cannot be removed from the
client, so nothing is removed and the method returns false.
Returns: boolean - true if any row was removed.
selectAll
rowSelection.selectAll([scope]) ⇒ boolean
Selects every selectable row in the scope.
| Param | Type | Description |
|---|---|---|
| [scope] | string | optional 'all', 'filtered', or 'currentPage'. Defaults to the selectAll setting. |
Returns: boolean - true if the selection changed.
selectRows
rowSelection.selectRows(rows) ⇒ boolean
Selects the rows. Rows that cannot be selected are skipped. In the 'singleRow' mode, only the
last row of the list is selected, and every other row is deselected.
| Param | Type | Description |
|---|---|---|
| rows | Array<number> | Visual row indexes. |
Returns: boolean - true if the selection changed.
setServerSelection
rowSelection.setServerSelection(selection) ⇒ boolean
Replaces the selection of a server-backed grid (the DataProvider
plugin), for example to restore one you saved with RowSelection#getServerSelection.
| Param | Type | Description |
|---|---|---|
| selection | object | The selection. |
| selection.selectAll | boolean | Whether every row is selected, except toggledRowIds. |
| selection.toggledRowIds | Array | The row ids that differ from selectAll. |
Returns: boolean - true if the selection was applied.
toggleAll
rowSelection.toggleAll() ⇒ boolean
Toggles every selectable row in the scope, the way a click on the “select all” checkbox does: a checked checkbox deselects them, an unchecked or mixed one selects them.
Returns: boolean - true if the selection changed.
toggleRow
rowSelection.toggleRow(row) ⇒ boolean
Toggles the selection of the row.
| Param | Type | Description |
|---|---|---|
| row | number | Visual row index. |
Returns: boolean - true if the selection changed.
updatePlugin
rowSelection.updatePlugin()
Updates the plugin’s state.
This method is executed when updateSettings() is invoked with any of the following configuration options: