GridSelection

Configs

selectionMode: GridSelectionModeAlso a property

Selection configuration settings, change these properties to control how selection works and what can be selected.

When configuring (creating an instance), set this to an object containing only those properties you want to change.

new Grid({
    selectionMode : {
       // Enables cell selection
       cell       : true,
       // Enabled cell and record selection by dragging
       dragSelect : true,
       // Enables selection of a column's cells by clicking the column header
       column     : true,
       // Shows a row number column which, when clicked, selected the row/record
       rowNumber  : true
    }
});

After the configuring is done, these properties will be monitored for changes, making it possible to alter the selection configuration at any time.

// Adds a selection checkbox column and makes that the only way to select
grid.selectionMode.checkboxOnly = true;

// Deactivates the auto selection of rows and cells when keyboard navigating
grid.selectionMode.selectOnKeyboardNavigation = false;

Properties

Class hierarchy

isGridSelection: Boolean= truereadonly

Identifies an object as an instance of GridSelection class, or subclass thereof.

isGridSelection: Boolean= truereadonlystatic

Identifies an object as an instance of GridSelection class, or subclass thereof.

Selection

selectedCell: GridLocation

In cell selection mode, this will get the cell selector for the (last) selected cell. Set to an available cell selector to select only that cell. Or use selectCell() instead.

selectedCellCSSSelector: Stringreadonly

CSS selector for the currently selected cell. Format is "[data-index=index] [data-column-id=column]".

selectedCells: GridLocation[]

In cell selection mode, this will get the cell selectors for all selected cells. Set to an array of available cell selectors. Or use selectCells() instead.

selectedRecord: Model

The last selected record. Set to select a row or use Grid#selectRow. Set to null to deselect all

selectedRecords: Model[]

Selected records.

If deselectFilteredOutRecords is false (default) this will include selected records which has been filtered out.

If preserveSelectionOnPageChange is true (defaults to false) this will include selected records on all pages.

If selectRecordOnCell is true (default) this will include any record which has at least one cell selected.

Can be set as array of ids:

grid.selectedRecords = [1, 2, 4, 6]

selectedRows: Model[]

Selected records. Records selected via cell selection is excluded.

If deselectFilteredOutRecords is false (default) this will include selected records which has been filtered out.

If preserveSelectionOnPageChange is true (defaults to false) this will include selected records on all pages.

if selectRecordOnCell is false this will return same records as selectedRecords.

Can be set as array of ids:

grid.selectedRecords = [1, 2, 4, 6]

selectionMode: GridSelectionModeAlso a config

Selection configuration settings, change these properties to control how selection works and what can be selected.

When configuring (creating an instance), set this to an object containing only those properties you want to change.

new Grid({
    selectionMode : {
       // Enables cell selection
       cell       : true,
       // Enabled cell and record selection by dragging
       dragSelect : true,
       // Enables selection of a column's cells by clicking the column header
       column     : true,
       // Shows a row number column which, when clicked, selected the row/record
       rowNumber  : true
    }
});

After the configuring is done, these properties will be monitored for changes, making it possible to alter the selection configuration at any time.

// Adds a selection checkbox column and makes that the only way to select
grid.selectionMode.checkboxOnly = true;

// Deactivates the auto selection of rows and cells when keyboard navigating
grid.selectionMode.selectOnKeyboardNavigation = false;

Functions

deselectAll

Deselects all selected rows and cells. If store is filtered, this will unselect all visible rows only. Any selections made prior to filtering remains.

Parameter	Type	Description
`removeCurrentRecordsOnly`	Boolean	Pass `false` to clear all selected records, and `true` to only clear selected records in the current set of records
`silent`	Boolean	Pass `true` not to fire any event upon selection change

deselectCell

If in cell selection mode, this deselects one cell. If not, this deselects the cell's record.

Parameter	Type	Description
`cellSelector`	GridLocationConfig \| GridLocation

Returns: GridLocation -

Normalized cell selector

deselectCells

If in cell selection mode, this deselects a number of cells. If not, this deselects corresponding records.

Parameter	Type	Description
`cellSelectors`	GridLocationConfig[] \| GridLocation[]

Returns: GridLocation[] -

Normalized cell selectors

deselectRow

Deselect one row

Parameter	Type	Description
`recordOrId`	Model \| String \| Number	Record or an id for a record

deselectRows

Deselect one or more rows

Parameter	Type	Description
`recordOrIds`	Model \| String \| Number \| Model[] \| String[] \| Number[]	An array of records or ids for a record

isCellSelected

Checks whether a cell is selected.

Parameter	Type	Description
`cellSelector`	GridLocationConfig \| GridLocation	Cell selector { id: x, column: xx }
`includeRow`	Boolean	to also check if row is selected

Returns: Boolean -

true if cell is selected, otherwise false

isSelectable

Checks whether a cell or row can be selected.

Parameter	Type	Description
`recordCellOrId`	Model \| GridLocationConfig \| GridLocation \| String \| Number	Record or cell or record id

Returns: Boolean -

true if cell or row can be selected, otherwise false

isSelected

Checks whether a row is selected. Will not check if any of a row's cells are selected.

Parameter	Type	Description
`cellSelectorOrId`	GridLocationConfig \| GridLocation \| String \| Number \| Model	Cell selector { id: x, column: xx } or row id, or record

Returns: Boolean -

true if row is selected, otherwise false

selectAll

This selects all rows. If store is filtered, this will merge the selection of all visible rows with any selection made prior to filtering.

selectCell

If in cell selection mode, this selects one cell. If not, this selects the cell's record.

Parameter	Type	Description
`options`	GridLocationConfig \| GridLocation \| Object	A cell selector ({ id: rowId, columnId: 'columnId' }) or a config object
`options.cell`	GridLocationConfig \| GridLocation	A cell selector ({ id: rowId, columnId: 'columnId' })
`options.scrollIntoView`	Boolean \| BryntumScrollOptions	Specify `false` to prevent row from being scrolled into view
`options.addToSelection`	Boolean	Specify `true` to add to selection, defaults to `false` which replaces
`options.silent`	Boolean	Specify `true` to not trigger any events when selecting the cell

Returns: GridLocation -

Cell selector

selectCellRange

Selects a range of cells, from a cell selector (GridLocation) to another

Parameter	Type	Description
`from`	GridLocation \| GridLocationConfig
`to`	GridLocation \| GridLocationConfig

selectCells

If in cell selection mode, this selects a number of cells. If not, this selects corresponding records.

Parameter	Type	Description
`options`	Object \| GridLocationConfig[] \| GridLocation[]	An array of cell selectors ({ id: rowId, columnId: 'columnId' }) or a config object
`options.cells`	GridLocationConfig[] \| GridLocation[]	An array of cell selectors { id: rowId, columnId: 'columnId' }
`options.scrollIntoView`	Boolean \| BryntumScrollOptions	Specify `false` to prevent row from being scrolled into view
`options.addToSelection`	Boolean	Specify `true` to add to selection, defaults to `false` which replaces
`options.silent`	Boolean	Specify `true` to not trigger any events when selecting the cell

Returns: GridLocation[] -

Cell selectors

selectRange

Selects rows corresponding to a range of records (from fromId to toId)

Parameter	Type	Description
`fromId`	String \| Number
`toId`	String \| Number

selectRow

Select one row

Parameter	Type	Description
`options`	Object \| Model \| String \| Number	A record or id to select or a config object describing the selection
`options.record`	Model \| String \| Number	Record or record id, specifying null will deselect all
`options.column`	Column	The column to scroll into view if `scrollIntoView` is not specified as `false`. Defaults to the grid's first column.
`options.scrollIntoView`	Boolean \| BryntumScrollOptions	Specify `false` to prevent row from being scrolled into view
`options.addToSelection`	Boolean	Specify `true` to add to selection, defaults to `false` which replaces

selectRows

Select one or more rows

Parameter	Type	Description
`options`	Object \| Model[] \| String[] \| Number[]	An array of records or ids for a record or a config object describing the selection
`options.records`	Model[] \| String[] \| Number[]	An array of records or ids for a record
`options.column`	Column	The column to scroll into view if `scrollIntoView` is not specified as `false`. Defaults to the grid's first column.
`options.scrollIntoView`	Boolean \| BryntumScrollOptions	Specify `false` to prevent row from being scrolled into view
`options.addToSelection`	Boolean	Specify `true` to add to selection, defaults to `false` which replaces

spliceSelectedRecords

Removes and adds records to/from the selection at the same time. Analogous to the Array splice method.

Note that if records that are specified for removal are also in the toAdd array, then those records are not removed and then appended. They remain in the same position relative to all remaining records.

Parameter	Type	Description
`index`	Number	Index at which to remove a block of records. Only valid if the second, `toRemove` argument is a number.
`toRemove`	Model[] \| Number	Either the number of records to remove starting at the passed `index`, or an array of records to remove (If an array is passed, the `index` is ignored).
`toAdd`	Model[] \| Model	A record, or an array of records to add.

Events

beforeSelectionChange

Fires before the selection changes. Returning false from a listener prevents the change

// Adding a listener using the "on" method
gridSelection.on('beforeSelectionChange', ({ action, mode, source, deselected, selected, selection, deselectedCells, selectedCells, cellSelection }) => {

});

Parameter	Type	Description
`action`	String	`'select'`/`'deselect'`
`mode`	row \| cell	`'row'`/`'cell'`
`source`	Grid
`deselected`	Model[]	The records to be deselected in this operation.
`selected`	Model[]	The records to be selected in this operation.
`selection`	Model[]	The records in the current selection, before applying `selected` and `deselected`
`deselectedCells`	GridLocation[]	The cells to be deselected in this operation.
`selectedCells`	GridLocation[]	The cells to be selected in this operation.
`cellSelection`	GridLocation[]	The cells in the current selection, before applying `selectedCells` and `deselectedCells`

dragSelecting

Fires while drag selecting. UI will update with current range, but the cells will not be selected until mouse up. This event can be listened for to perform actions while drag selecting.

// Adding a listener using the "on" method
gridSelection.on('dragSelecting', ({ source, selectedCells, selectedRecords }) => {

});

Parameter	Type	Description
`source`	Grid
`selectedCells`	GridLocationConfig[] \| GridLocation[]	The cells that is currently being dragged over
`selectedRecords`	Model[]	The records that is currently being dragged over

selectionChange

The selection has been changed.

// Adding a listener using the "on" method
gridSelection.on('selectionChange', ({ action, mode, source, deselected, selected, selection, deselectedCells, selectedCells, cellSelection }) => {

});

Parameter	Type	Description
`action`	select \| deselect	`'select'`/`'deselect'`
`mode`	row \| cell	`'row'`/`'cell'`
`source`	Grid
`deselected`	Model[]	The records deselected in this operation.
`selected`	Model[]	The records selected in this operation.
`selection`	Model[]	The records in the new selection.
`deselectedCells`	GridLocation[]	The cells deselected in this operation.
`selectedCells`	GridLocation[]	The cells selected in this operation.
`cellSelection`	GridLocation[]	The cells in the new selection.

selectionModeChange

The selectionMode configuration has been changed.

// Adding a listener using the "on" method
gridSelection.on('selectionModeChange', ({ selectionMode }) => {

});

Parameter	Type	Description
`selectionMode`	Object	The new selectionMode

Event handlers

onBeforeSelectionChange

Called before the selection changes. Returning false from a listener prevents the change

new GridSelection({
    onBeforeSelectionChange({ action, mode, source, deselected, selected, selection, deselectedCells, selectedCells, cellSelection }) {

    }
});

Parameter	Type	Description
`action`	String	`'select'`/`'deselect'`
`mode`	row \| cell	`'row'`/`'cell'`
`source`	Grid
`deselected`	Model[]	The records to be deselected in this operation.
`selected`	Model[]	The records to be selected in this operation.
`selection`	Model[]	The records in the current selection, before applying `selected` and `deselected`
`deselectedCells`	GridLocation[]	The cells to be deselected in this operation.
`selectedCells`	GridLocation[]	The cells to be selected in this operation.
`cellSelection`	GridLocation[]	The cells in the current selection, before applying `selectedCells` and `deselectedCells`

onDragSelecting

Called while drag selecting. UI will update with current range, but the cells will not be selected until mouse up. This event can be listened for to perform actions while drag selecting.

new GridSelection({
    onDragSelecting({ source, selectedCells, selectedRecords }) {

    }
});

Parameter	Type	Description
`source`	Grid
`selectedCells`	GridLocationConfig[] \| GridLocation[]	The cells that is currently being dragged over
`selectedRecords`	Model[]	The records that is currently being dragged over

onSelectionChange

The selection has been changed.

new GridSelection({
    onSelectionChange({ action, mode, source, deselected, selected, selection, deselectedCells, selectedCells, cellSelection }) {

    }
});

Parameter	Type	Description
`action`	select \| deselect	`'select'`/`'deselect'`
`mode`	row \| cell	`'row'`/`'cell'`
`source`	Grid
`deselected`	Model[]	The records deselected in this operation.
`selected`	Model[]	The records selected in this operation.
`selection`	Model[]	The records in the new selection.
`deselectedCells`	GridLocation[]	The cells deselected in this operation.
`selectedCells`	GridLocation[]	The cells selected in this operation.
`cellSelection`	GridLocation[]	The cells in the new selection.

onSelectionModeChange

The selectionMode configuration has been changed.

new GridSelection({
    onSelectionModeChange({ selectionMode }) {

    }
});

Parameter	Type	Description
`selectionMode`	Object	The new selectionMode

Typedefs

GridSelectionMode

Parameter	Type	Description
`cell`	Boolean	Set to `true` to enable cell selection. This takes precedence over row selection, but rows can still be selected programmatically or with checkbox or `RowNumber` selection. Required for `column` selection
`row`	Boolean	Set to `true` to enable row selection. This takes precedence over row selection. Required for `row` selection
`multiSelect`	Boolean	Allow multiple selection with ctrl and `[Shift + Click]` or with `checkbox` selection. Required for `dragSelect` and `column` selection
`alwaysMultiSelect`	Boolean	Allow multiple selection by simply clicking a row/checkbox
`checkbox`	Boolean \| CheckColumnConfig	Set to `true` to add a checkbox selection column to the grid, or pass a config object for the CheckColumn. Note that the checkbox selection column should not be configured with a `field`, since it is linked to grid selection and not to record data
`checkboxIndex`	Number \| String	Positions the checkbox column at the provided index or to the right of a provided column id. Defaults to `0` or to the right of an included `RowNumberColumn`
`checkboxOnly`	Boolean	Select rows only when clicking in the checkbox column. Requires cell selection config to be `false` and checkbox to be set to `true`. This setting was previously named `rowCheckboxSelection`
`showCheckAll`	Boolean	Set to `true` to add a checkbox to the selection column header to select/deselect all rows. Requires checkbox to also be set to `true`. Not supported when `Store` is configured with lazyLoad
`showCheckAllInGroupRows`	Boolean	Set to `true` to add a checkbox to group rows to be able to check/uncheck all group members
`deselectFilteredOutRecords`	Boolean	Set to `true` to deselect records when they are filtered out
`includeChildren`	Boolean \| String	Set to `true` to also select/deselect child nodes when a parent node is selected by toggling the checkbox. Set to `'always'` to always select/deselect child nodes.
`includeParents`	Boolean \| all \| some	Set to `all` or `true` to auto select parent if all its children gets selected. If one gets deselected, the parent will also be deselected. Set to 'some' to select parent if one of its children gets selected. The parent will be deselected if all children gets deselected.
`preserveSelectionOnPageChange`	Boolean	In `row` selection mode, this flag controls whether the Grid should preserve its selection when loading a new page of a paged data store. Defaults to `false`.
`preserveSelectionOnDatasetChange`	Boolean	In `row` selection mode, this flag controls whether the Grid should preserve its selection of cells / rows when loading a new dataset (assuming the selected records are included in the newly loaded dataset)
`deselectOnClick`	Boolean	Toggles whether the Grid should deselect a selected row or cell when clicking it
`dragSelect`	Boolean	Set to `true` to enable multiple selection by dragging. Requires to also be set to `true`. Also requires the RowReorder feature to be set to gripOnly
`selectOnKeyboardNavigation`	Boolean	Set to `false` to disable auto-selection by keyboard navigation. This will activate the `select` keyboard shortcut
`column`	Boolean	Set to `true` to be able to select whole columns of cells by clicking the header. Requires cell to be set to `true`. Not supported when `Store` is configured with lazyLoad
`rowNumber`	Boolean \| RowNumberColumnConfig	Set to `true`, or a config object to add a `RowNumberColumn` which, when clicked, selects the row
`selectRecordOnCell`	Boolean	Set to `false` not to include the record in the `selectedRecords` array when one of the record row's cells is selected