fix: respect multiSelect in checkbox and row keyboard selection (#2573)

* fix: respect `multiSelect` in checkbox and row keyboard selection

Author: ghiscoding

demos/aurelia/src/examples/slickgrid/example30.ts

@@ -497,7 +497,6 @@ export class Example30 {
       preHeaderPanelHeight: 28,
       enableCheckboxSelector: true,
       enableSelection: true,
-      multiSelect: false,
       checkboxSelector: {
         hideInFilterHeaderRow: false,
         hideInColumnTitleRow: true,

demos/react/src/examples/slickgrid/Example30.tsx

@@ -492,7 +492,6 @@ const Example30: React.FC = () => {
       preHeaderPanelHeight: 28,
       enableCheckboxSelector: true,
       enableSelection: true,
-      multiSelect: false,
       checkboxSelector: {
         hideInFilterHeaderRow: false,
         hideInColumnTitleRow: true,

demos/vue/src/components/Example30.vue

@@ -456,7 +456,6 @@ function defineGrid() {
     preHeaderPanelHeight: 28,
     enableCheckboxSelector: true,
     enableSelection: true,
-    multiSelect: false,
     checkboxSelector: {
       hideInFilterHeaderRow: false,
       hideInColumnTitleRow: true,

docs/grid-functionalities/composite-editor-modal.md

@@ -143,6 +143,8 @@ Mass Update allows you to apply changes (from the modal form) to the entire data
 
 Note however that there is a subtle difference compare to the Create Item action, you need to specifically tag which column will show up in the Mass Update and you need to do that by adding `massUpdate: true` flag inside the `editor` property of each column definition that you wish to be included in the form.
 
+Important: `selectionOptions.selectActiveRow: false` is commonly used for checkbox-based multi-row workflows, but you must also keep `multiSelect` enabled (default `true`), otherwise `mass-selection` and `auto-mass` will not work as expected because only one row can stay selected at a time.
+
 `auto-mass` option: If you decide to use Mass Update and Mass Selection and wish to only expose 1 button to do the action and let the system decide if it's doing a Mass Update or a Mass Selection change, you can use the modal type `auto-mass` (if it detect that some rows are selected it will use Mass Selection or else Mass Update). From our experience, user prefer to expose the 2 separate action buttons (less confusion), but this for you to decide, you have the option.
 
 ##### with TypeScript
@@ -237,6 +239,8 @@ example class MyCompositeDemo {
 ## Mass Selection
 Similar to the Mass Update but apply changes only on the selected rows. The setup is nearly identical to the Mass Update, just make sure to display appropriate modal title. Also note that you also need to add `massUpdate: true` flag inside the `editor` property of each column definition that you wish to be included in the Mass Selection changes form.
 
+**Important**: Mass Selection requires real multi-row selection, so even if you use `selectionOptions.selectActiveRow: false`, you must keep `multiSelect` enabled (default `true`); with `multiSelect: false`, only one row can remain selected and the modal will not behave as expected.
+
 Refer to the [Mass Update](#mass-update) section for code sample.
 
 `auto-mass` option: If you decide to use Mass Update and Mass Selection and wish to only expose 1 button to do the action and let the system decide if it's doing a Mass Update or a Mass Selection change, you can use the modal type `auto-mass` (if it detect that some rows are selected it will use Mass Selection or else Mass Update). From our experience, user prefer to expose the 2 separate action buttons (less confusion), but this for you to decide, you have the option.

docs/grid-functionalities/row-selection.md

@@ -6,6 +6,7 @@
 - [Disable Custom Rows Selections via `selectableOverride`](#disable-custom-rows-selections-via-selectableoverride)
 - [Disable External Button when having Empty Selection](#disable-external-button-when-having-empty-selection)
 - [Change Row Selections](#change-row-selections)
+- [Understanding the multiSelect Option](#understanding-the-multiselect-option)
 - Troubleshooting
   - [Adding a Column dynamically is removing the Row Selection column, why is that?](#adding-a-column-dynamically-is-removing-the-row-selection-column-why-is-that)
 - [Hybrid Selection Model (cell+row selection)](#hybrid-selection-model-and-drag-fill)
@@ -80,7 +81,7 @@ gridObjChanged(grid) {
 ```
 
 ## Multiple Row Selections
-As for multiple row selections, you need to disable `enableCellNavigation` and enable `enableCheckboxSelector` and `enableRowSelection`. Then as describe earlier, you will subscribe to `onSelectedRowsChanged` (for that you need to bind to `(gridChanged)`). There are 2 ways to choose for the implementation of a row selection, option **1.** is the most common option and is the recommend way of doing it.
+As for multiple row selections, you need to enable `enableCheckboxSelector` and `enableRowSelection`, keep `multiSelect` enabled (default is `true`), and typically use `selectionOptions.selectActiveRow: false` when you do not want active-row clicks to interfere with checkbox-based multi-selection. Then as describe earlier, you will subscribe to `onSelectedRowsChanged` (for that you need to bind to `(gridChanged)`). There are 2 ways to choose for the implementation of a row selection, option **1.** is the most common option and is the recommend way of doing it.
 
 ### 1. with Custom Events (preferred way)
 You can also do it through a Custom Event listener since all SlickGrid events are exposed as Custom Events. For more info see [Wiki - OnEvents](grid-dataview-events.md)
@@ -112,6 +113,7 @@ export class Example1 {
         // True (Single Selection), False (Multiple Selections)
         selectActiveRow: false
       },
+      // keep `multiSelect` enabled (default) for actual multiple row selection
     }
   }
 
@@ -138,6 +140,7 @@ export class Example1 {
         // True (Single Selection), False (Multiple Selections)
         selectActiveRow: false
       },
+      // keep `multiSelect` enabled (default) for actual multiple row selection
     }
   }
 
@@ -339,6 +342,30 @@ export class Example1 {
 }
 ```
 
+## Understanding the `multiSelect` Option
+The `multiSelect` grid option is a critical setting that controls how row selection works across all selection methods (checkboxes, keyboard navigation, and click handlers). Understanding this option is key to implementing the correct selection behavior for your use case.
+
+### `multiSelect: false` (Single Selection Mode)
+When `multiSelect: false`, the grid enforces **strict single selection**:
+- **Checkbox Selection**: Clicking a checkbox selects only that row. Clicking a checkbox that's already selected will **deselect** it (toggle behavior). Only one row can be selected at a time.
+- **Keyboard Selection**: Using Shift+Arrow keys to extend a range will select only the current row (range is clamped to a single row). Regular arrow navigation moves between rows but doesn't change selection.
+- **Overall Behavior**: At most one row is selected at any time. If you programmatically select a row while another is selected, only the new row remains selected.
+
+### `multiSelect: true` (Multiple Selection Mode)
+When `multiSelect: true`, the grid allows **multiple rows to be selected**:
+- **Checkbox Selection**: Clicking a checkbox adds or removes that row from the selection set. Multiple rows can be checked independently.
+- **Keyboard Selection**: Using Shift+Arrow keys extends the selection range to include multiple rows. Ctrl/Cmd+Click or Shift+Click can be used to build complex selections.
+- **Overall Behavior**: Multiple rows can be selected and retained in the selection set.
+
+### Selection Methods & `multiSelect`
+All row selection methods respect the `multiSelect` option:
+1. **Checkbox Selection** (when `enableCheckboxSelector: true`): Respects `multiSelect` setting
+2. **Keyboard Selection** (Shift+Arrow): Respects `multiSelect` setting
+3. **Programmatic Selection** (calling `setSelectedRows()`): Not restricted by `multiSelect` but subsequent UI interactions will respect it
+4. **Other Selection Handlers**: All adhere to the `multiSelect` constraint
+
+`selectionOptions.selectActiveRow` only controls whether activating a row also selects it; it does not override `multiSelect` and cannot enable multiple selection when `multiSelect: false`.
+
 ## Troubleshooting
 ### Adding a Column dynamically is removing the Row Selection column, why is that?
 The reason is because the Row Selection (checkbox) plugin is a special column and Slickgrid-Universal is adding an extra column dynamically for the Row Selection checkbox and that is **not** reflected in your local copy of `columns`. To address this issue, you need to get the Slickgrid-Universal internal copy of all columns (including the extra columns), you can get it via `getAllColumnDefinitions()` from the Grid Service and then you can use to that array and that will work.

frameworks/angular-slickgrid/docs/grid-functionalities/composite-editor-modal.md

@@ -108,6 +108,8 @@ Mass Update allows you to apply changes (from the modal form) to the entire data
 
 Note however that there is a subtle difference compare to the Create Item action, you need to specifically tag which column will show up in the Mass Update and you need to do that by adding `massUpdate: true` flag inside the `editor` property of each column definition that you wish to be included in the form.
 
+Important: `selectionOptions.selectActiveRow: false` is commonly used for checkbox-based multi-row workflows, but you must also keep `multiSelect` enabled (default `true`), otherwise `mass-selection` and `auto-mass` will not work as expected because only one row can stay selected at a time.
+
 `auto-mass` option: If you decide to use Mass Update and Mass Selection and wish to only expose 1 button to do the action and let the system decide if it's doing a Mass Update or a Mass Selection change, you can use the modal type `auto-mass` (if it detect that some rows are selected it will use Mass Selection or else Mass Update). From our experience, user prefer to expose the 2 separate action buttons (less confusion), but this for you to decide, you have the option.
 
 ##### with TypeScript
@@ -166,6 +168,8 @@ example class MyCompositeDemo {
 ## Mass Selection
 Similar to the Mass Update but apply changes only on the selected rows. The setup is nearly identical to the Mass Update, just make sure to display appropriate modal title. Also note that you also need to add `massUpdate: true` flag inside the `editor` property of each column definition that you wish to be included in the Mass Selection changes form.
 
+**Important**: Mass Selection requires real multi-row selection, so even if you use `selectionOptions.selectActiveRow: false`, you must keep `multiSelect` enabled (default `true`); with `multiSelect: false`, only one row can remain selected and the modal will not behave as expected.
+
 Refer to the [Mass Update](#mass-update) section for code sample.
 
 `auto-mass` option: If you decide to use Mass Update and Mass Selection and wish to only expose 1 button to do the action and let the system decide if it's doing a Mass Update or a Mass Selection change, you can use the modal type `auto-mass` (if it detect that some rows are selected it will use Mass Selection or else Mass Update). From our experience, user prefer to expose the 2 separate action buttons (less confusion), but this for you to decide, you have the option.

frameworks/angular-slickgrid/docs/grid-functionalities/row-selection.md

@@ -6,6 +6,7 @@
 - [Disable Custom Rows Selections via `selectableOverride`](#disable-custom-rows-selections-via-selectableoverride)
 - [Disable External Button when having Empty Selection](#disable-external-button-when-having-empty-selection)
 - [Change Row Selections](#change-row-selections)
+- [Understanding the multiSelect Option](#understanding-the-multiselect-option)
 - Troubleshooting
   - [Adding a Column dynamically is removing the Row Selection column, why is that?](#adding-a-column-dynamically-is-removing-the-row-selection-column-why-is-that)
 - [Hybrid Selection Model (cell+row selection)](#hybrid-selection-model-and-drag-fill)
@@ -54,7 +55,7 @@ onSelectedRowsChanged(e, args) {
 ```
 
 ## Multiple Row Selections
-As for multiple row selections, you need to provide an extra grid option of `rowSelectionOptions` which is an object and within it, you need to disable the `selectActiveRow` flag. The other configurations are the same as a Single Selection, which is to enable `enableCheckboxSelector` and `enableSelection` (or `enableRowSelection` in <=9.x). Then as describe earlier, you will subscribe to `onSelectedRowsChanged` (for that you need to bind to `(gridChanged)`).
+As for multiple row selections, you need to provide `selectionOptions.selectActiveRow: false` and keep `multiSelect` enabled (default is `true`). The other configurations are the same as a Single Selection, which is to enable `enableCheckboxSelector` and `enableSelection` (or `enableRowSelection` in <=9.x). Then as describe earlier, you will subscribe to `onSelectedRowsChanged` (for that you need to bind to `(gridChanged)`).
 
 #### View
 ```html
@@ -83,6 +84,7 @@ export class Example1 implements OnInit {
         // True (Single Selection), False (Multiple Selections)
         selectActiveRow: false
       },
+      // keep `multiSelect` enabled (default) for actual multiple row selection
     }
   }
 
@@ -295,6 +297,28 @@ copyDraggedCellRange(args: OnDragReplaceCellsEventArgs) {
 }
 ```
 
+## Understanding the `multiSelect` Option
+The `multiSelect` grid option is a critical setting that controls how row selection works across all selection methods (checkboxes, keyboard navigation, and click handlers). Understanding this option is key to implementing the correct selection behavior for your use case.
+
+### `multiSelect: false` (Single Selection Mode)
+When `multiSelect: false`, the grid enforces **strict single selection**:
+- **Checkbox Selection**: Clicking a checkbox selects only that row. Clicking a checkbox that's already selected will **deselect** it (toggle behavior). Only one row can be selected at a time.
+- **Keyboard Selection**: Using Shift+Arrow keys to extend a range will select only the current row (range is clamped to a single row). Regular arrow navigation moves between rows but doesn't change selection.
+- **Overall Behavior**: At most one row is selected at any time. If you programmatically select a row while another is selected, only the new row remains selected.
+
+### `multiSelect: true` (Multiple Selection Mode)
+When `multiSelect: true`, the grid allows **multiple rows to be selected**:
+- **Checkbox Selection**: Clicking a checkbox adds or removes that row from the selection set. Multiple rows can be checked independently.
+- **Keyboard Selection**: Using Shift+Arrow keys extends the selection range to include multiple rows. Ctrl/Cmd+Click or Shift+Click can be used to build complex selections.
+- **Overall Behavior**: Multiple rows can be selected and retained in the selection set.
+
+### Selection Methods & `multiSelect`
+All row selection methods respect the `multiSelect` option:
+1. **Checkbox Selection** (when `enableCheckboxSelector: true`): Respects `multiSelect` setting
+2. **Keyboard Selection** (Shift+Arrow): Respects `multiSelect` setting
+3. **Programmatic Selection** (calling `setSelectedRows()`): Not restricted by `multiSelect` but subsequent UI interactions will respect it
+4. **Other Selection Handlers**: All adhere to the `multiSelect` constraint
+
 ## Troubleshooting
 ### Adding a Column dynamically is removing the Row Selection column, why is that?
 The reason is because the Row Selection (checkbox) plugin is a special column and Angular-Slickgrid is adding an extra column dynamically for the Row Selection checkbox and that is **not** reflected in your local copy of `columns`. To address this issue, you need to get the Angular-Slickgrid internal copy of all columns (including the extra columns), you can get it via `getAllColumnDefinitions()` from the Grid Service and then you can use to that array and that will work.

frameworks/angular-slickgrid/src/demos/examples/example30.component.ts

@@ -504,7 +504,6 @@ export class Example30Component implements OnDestroy, OnInit {
       preHeaderPanelHeight: 28,
       enableCheckboxSelector: true,
       enableSelection: true,
-      multiSelect: false,
       checkboxSelector: {
         hideInFilterHeaderRow: false,
         hideInColumnTitleRow: true,

frameworks/aurelia-slickgrid/docs/grid-functionalities/composite-editor-modal.md

@@ -108,6 +108,8 @@ Mass Update allows you to apply changes (from the modal form) to the entire data
 
 Note however that there is a subtle difference compare to the Create Item action, you need to specifically tag which column will show up in the Mass Update and you need to do that by adding `massUpdate: true` flag inside the `editor` property of each column definition that you wish to be included in the form.
 
+Important: `selectionOptions.selectActiveRow: false` is commonly used for checkbox-based multi-row workflows, but you must also keep `multiSelect` enabled (default `true`), otherwise `mass-selection` and `auto-mass` will not work as expected because only one row can stay selected at a time.
+
 `auto-mass` option: If you decide to use Mass Update and Mass Selection and wish to only expose 1 button to do the action and let the system decide if it's doing a Mass Update or a Mass Selection change, you can use the modal type `auto-mass` (if it detect that some rows are selected it will use Mass Selection or else Mass Update). From our experience, user prefer to expose the 2 separate action buttons (less confusion), but this for you to decide, you have the option.
 
 ##### with TypeScript
@@ -166,6 +168,8 @@ example class MyCompositeDemo {
 ## Mass Selection
 Similar to the Mass Update but apply changes only on the selected rows. The setup is nearly identical to the Mass Update, just make sure to display appropriate modal title. Also note that you also need to add `massUpdate: true` flag inside the `editor` property of each column definition that you wish to be included in the Mass Selection changes form.
 
+**Important**: Mass Selection requires real multi-row selection, so even if you use `selectionOptions.selectActiveRow: false`, you must keep `multiSelect` enabled (default `true`); with `multiSelect: false`, only one row can remain selected and the modal will not behave as expected.
+
 Refer to the [Mass Update](#mass-update) section for code sample.
 
 `auto-mass` option: If you decide to use Mass Update and Mass Selection and wish to only expose 1 button to do the action and let the system decide if it's doing a Mass Update or a Mass Selection change, you can use the modal type `auto-mass` (if it detect that some rows are selected it will use Mass Selection or else Mass Update). From our experience, user prefer to expose the 2 separate action buttons (less confusion), but this for you to decide, you have the option.