Skip to content

RowSelection

See the Row selection guide for examples and configuration details.

Options

rowSelection

Can be set at: grid

Source code

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:

SettingDescription
falseDisable the RowSelection plugin
trueEnable the RowSelection plugin with its defaults
An objectEnable the plugin and configure it

If you set the rowSelection option to an object, you can configure the following options:

OptionPossible settingsDefault
mode'multiRow' | 'singleRow''multiRow'
checkboxesA boolean, or a function (rowData, physicalRow) => booleantrue
headerCheckboxA booleantrue
selectAll'all' | 'filtered' | 'currentPage''all'
enableClickSelectiontrue | false | 'enableSelection' | 'enableDeselection'false
isRowSelectableA function (rowData, physicalRow) => boolean-
hideDisabledCheckboxesA booleanfalse
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 defaults
rowSelection: true,
// "select all" acts on the filtered rows, and archived rows cannot be selected
rowSelection: {
selectAll: 'filtered',
isRowSelectable: (rowData) => rowData.status !== 'archived',
},

Members

DEFAULT_SETTINGS

Source code

RowSelection.DEFAULT_SETTINGS

Returns the default settings applied when the plugin is enabled without explicit configuration.

LICENSE

Source code

RowSelection.LICENSE

Returns the license token of the plugin, its display name, where it is checked, and the tokens it requires.

PLUGIN_KEY

Source code

RowSelection.PLUGIN_KEY

Returns the plugin key used to identify this plugin in Handsontable settings.

PLUGIN_PRIORITY

Source code

RowSelection.PLUGIN_PRIORITY

Returns the priority order used to determine the order in which plugins are initialized.

SETTINGS_VALIDATORS

Source code

RowSelection.SETTINGS_VALIDATORS

Returns the validators the plugin settings are checked against.

Methods

deselectAll

Source code

rowSelection.deselectAll([scope]) ⇒ boolean

Deselects every row in the scope.

ParamTypeDefaultDescription
[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

Source code

rowSelection.deselectRows(rows) ⇒ boolean

Deselects the rows.

ParamTypeDescription
rowsArray<number>Visual row indexes.

Returns: boolean - true if the selection changed.

destroy

Source code

rowSelection.destroy()

Destroys the plugin instance.

disablePlugin

Source code

rowSelection.disablePlugin()

Disables the plugin functionality for this Handsontable instance.

enablePlugin

Source code

rowSelection.enablePlugin()

Enables the plugin functionality for this Handsontable instance.

getBoundColumn

Source code

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

Source code

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

Source code

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

Source code

rowSelection.getSelectedPhysicalRows() ⇒ Array<number>

Returns the physical indexes of the selected rows, including the rows the Filters plugin filtered out.

getSelectedRows

Source code

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

Source code

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

Source code

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

Source code

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

Source code

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.

ParamTypeDescription
rownumberVisual row index.

isRowSelected

Source code

rowSelection.isRowSelected(row) ⇒ boolean

Checks whether the row is selected.

ParamTypeDescription
rownumberVisual row index.

removeSelectedRows

Source code

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

Source code

rowSelection.selectAll([scope]) ⇒ boolean

Selects every selectable row in the scope.

ParamTypeDescription
[scope]stringoptional 'all', 'filtered', or 'currentPage'. Defaults to the selectAll setting.

Returns: boolean - true if the selection changed.

selectRows

Source code

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.

ParamTypeDescription
rowsArray<number>Visual row indexes.

Returns: boolean - true if the selection changed.

setServerSelection

Source code

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.

ParamTypeDescription
selectionobjectThe selection.
selection.selectAllbooleanWhether every row is selected, except toggledRowIds.
selection.toggledRowIdsArrayThe row ids that differ from selectAll.

Returns: boolean - true if the selection was applied.

toggleAll

Source code

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

Source code

rowSelection.toggleRow(row) ⇒ boolean

Toggles the selection of the row.

ParamTypeDescription
rownumberVisual row index.

Returns: boolean - true if the selection changed.

updatePlugin

Source code

rowSelection.updatePlugin()

Updates the plugin’s state.

This method is executed when updateSettings() is invoked with any of the following configuration options: