SelectionPlugin

Selection Plugin for tbw-grid

Adds cell, row, and range selection capabilities to the grid with full keyboard support. Whether you need simple cell highlighting or complex multi-range selections, this plugin has you covered.

Installation

import { SelectionPlugin } from '@toolbox-web/grid/plugins/selection';

Selection Modes

Configure the plugin with one of three modes via SelectionConfig:

• 'cell' - Single cell selection (default). Click cells to select individually.
• 'row' - Full row selection. Click anywhere in a row to select the entire row.
• 'range' - Rectangular selection. Click and drag or Shift+Click to select ranges.

Keyboard Shortcuts

Shortcut	Action
Arrow Keys	Move selection
Shift + Arrow	Extend selection (range mode)
Ctrl/Cmd + Click	Toggle selection (multi-select)
Shift + Click	Extend to clicked cell/row
Ctrl/Cmd + A	Select all (range mode)
Escape	Clear selection

> Note: When multiSelect: false, Ctrl/Shift modifiers are ignored — > clicks always select a single item.

CSS Custom Properties

Property	Description
--tbw-focus-background	Focused row background
--tbw-range-selection-bg	Range selection fill
--tbw-range-border-color	Range selection border

Examples

Basic row selection

grid.gridConfig = {
  columns: [...],
  plugins: [new SelectionPlugin({ mode: 'row' })],
};

Range selection with event handling

grid.gridConfig = {
  plugins: [new SelectionPlugin({ mode: 'range' })],
};

grid.on('selection-change', ({ mode, ranges }) => {
  console.log(`Selected ${ranges.length} ranges in ${mode} mode`);
});

Programmatic selection control

const plugin = grid.getPluginByName('selection');

// Get current selection
const selection = plugin.getSelection();
console.log(selection.ranges);

// Set selection programmatically
plugin.setRanges([{ from: { row: 0, col: 0 }, to: { row: 5, col: 3 } }]);

// Clear all selection
plugin.clearSelection();

See Also

• SelectionMode for detailed mode descriptions
• SelectionConfig for configuration options
• SelectionResult for the selection result structure
• Live Demos for interactive examples

Extends BaseGridPlugin

Inherited methods like attach(), detach(), afterRender(), etc. are documented in the base class.

Methods

getSelection()

Get the current selection as a unified result. Works for all selection modes and always returns ranges.

getSelection(): SelectionResult

Example

const selection = plugin.getSelection();
if (selection.ranges.length > 0) {
  const { from, to } = selection.ranges[0];
  // For cell mode: from === to (single cell)
  // For row mode: from.col = 0, to.col = lastCol (full row)
  // For range mode: rectangular selection
}

---

getSelectedCells()

Get all selected cells across all ranges.

getSelectedCells(): object[]

---

isCellSelected()

Check if a specific cell is in range selection.

isCellSelected(row: number, col: number): boolean

Parameters

Name	Type	Description
row	number
col	number

---

selectAll()

Select all selectable rows (row mode) or all cells (range mode).

In row mode, selects every row where isSelectable returns true (or all rows if no callback). In range mode, creates a single range spanning all rows and columns. Has no effect in cell mode.

selectAll(): void

Example

const plugin = grid.getPluginByName('selection');
plugin.selectAll(); // Selects everything in current mode

---

selectRows()

Select specific rows by index (row mode only). Replaces the current selection with the provided row indices. Indices that are out of bounds or fail the isSelectable check are ignored.

selectRows(indices: number[]): void

Parameters

Name	Type	Description
indices	number[]	Array of row indices to select

Example

const plugin = grid.getPluginByName('selection');
plugin.selectRows([0, 2, 4]); // Select rows 0, 2, and 4

---

getSelectedRowIndices()

Get the indices of all selected rows (convenience for row mode). Returns indices sorted in ascending order.

getSelectedRowIndices(): number[]

Example

const plugin = grid.getPluginByName('selection');
const rows = plugin.getSelectedRowIndices(); // [0, 2, 4]

---

getSelectedRows()

Get the actual row objects for the current selection.

Works across all selection modes:

• Row mode: Returns the row objects for all selected rows.
• Cell mode: Returns the single row containing the selected cell, or [].
• Range mode: Returns the unique row objects that intersect any selected range.

Row objects are resolved from the grid’s processed (sorted/filtered) row array, so they always reflect the current visual order.

getSelectedRows(): T[]

Example

const plugin = grid.getPluginByName('selection');
const selected = plugin.getSelectedRows(); // [{ id: 1, name: 'Alice' }, ...]

---

clearSelection()

Clear all selection.

clearSelection(): void

---

setRanges()

Set selected ranges programmatically.

setRanges(ranges: CellRange[]): void

Parameters

Name	Type	Description
ranges	CellRange[]

---