SelectionPlugin

Since v0.1.1

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

Configuration Options

Option	Type	Description
mode	SelectionMode | SelectionMode[]	Selection mode (default: 'cell').
multiSelect?	boolean	Allow multiple items to be selected simultaneously (default: true).
enabled?	boolean	Whether selection is enabled (default: true).
triggerOn?	SelectionTrigger	Mouse event type that triggers selection (default: ‘click’).
checkbox?	boolean	Show a checkbox column for row selection (row mode only).
isSelectable?	SelectableCallback<T>	Callback that determines whether a specific row or cell can be selected.

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
• SelectionConfig for interactive examples in the docs site

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' }, ...]

---

selectColumn() v2.8.0+

Toggle, add, or replace a column in the column-axis selection.

Column selection is identified by field name, so it survives column pinning, reordering, and virtualization recycling. The column must be present in the grid’s visible columns and must not be a utility column.

Only available when mode includes 'column'. With multiSelect: false, range/toggle options are ignored and the call always replaces the current selection with the single column.

selectColumn(field: string, options: object): void

Parameters

Name	Type	Description
field	string	The column field name to select.
options	object

---

deselectColumn() v2.8.0+

Remove a column from the column-axis selection. No-op if field isn’t selected.

deselectColumn(field: string): void

Parameters

Name	Type	Description
field	string

---

selectAllColumns() v2.8.0+

Select every selectable column. No-op when multiSelect: false or column mode isn’t enabled.

selectAllColumns(): void

---

clearColumnSelection() v2.8.0+

Clear column-axis selection only. Leaves any row/cell/range selection intact.

clearColumnSelection(): void

---

getSelectedColumns() v2.8.0+

Get the field names of all currently selected columns, in visible-column order. Returns an empty array when the column axis is inactive or empty.

getSelectedColumns(): readonly string[]

---

clearSelection()

Clear all selection (every axis).

clearSelection(): void

---

setRanges()

Set selected ranges programmatically.

setRanges(ranges: CellRange[]): void

Parameters

Name	Type	Description
ranges	CellRange[]

---