0
# Range Selection
1

2
Advanced spreadsheet-like range selection functionality enabling users to select rectangular areas of cells, rows, or columns with keyboard and mouse interactions.
3

4
## Capabilities
5

6
### Range Management
7

8
Core functions for managing cell ranges and retrieving range data.
9

10
```javascript { .api }
11
/**
12
 * Get data from all active ranges
13
 * @returns Array of data arrays for each range
14
 */
15
getRangesData(): any[][];
16

17
/**
18
 * Get all active range components
19
 * @returns Array of RangeComponent objects
20
 */
21
getRanges(): RangeComponent[];
22

23
/**
24
 * Add a new range selection
25
 * @param start - Starting cell, row, or column component
26
 * @param end - Ending cell, row, or column component (optional)
27
 * @returns RangeComponent representing the new range
28
 */
29
addRange(
30
  start: CellComponent | RowComponent | ColumnComponent, 
31
  end?: CellComponent | RowComponent | ColumnComponent
32
): RangeComponent;
33
```
34

35
**Range Configuration:**
36

37
```javascript { .api }
38
interface RangeSelectionOptions {
39
  selectableRange?: boolean | number;
40
  selectableRangeColumns?: boolean;
41
  selectableRangeRows?: boolean;
42
  selectableRangeClearCells?: boolean;
43
  selectableRangeClearCellsValue?: any;
44
  selectableRangeAutoFocus?: boolean;
45
}
46
```
47

48
### Component Range Access
49

50
Access range information from table components.
51

52
```javascript { .api }
53
// Added to CellComponent by SelectRange module
54
/**
55
 * Get all ranges that include this cell
56
 * @returns Array of RangeComponent objects
57
 */
58
getRanges(): RangeComponent[];
59

60
// Added to RowComponent by SelectRange module  
61
/**
62
 * Get all ranges that include this row
63
 * @returns Array of RangeComponent objects
64
 */
65
getRanges(): RangeComponent[];
66

67
// Added to ColumnComponent by SelectRange module
68
/**
69
 * Get all ranges that include this column
70
 * @returns Array of RangeComponent objects
71
 */
72
getRanges(): RangeComponent[];
73
```
74

75
**Usage Examples:**
76

77
```javascript
78
import { Tabulator } from "tabulator-tables";
79

80
// Enable range selection
81
const table = new Tabulator("#table", {
82
  data: [
83
    { id: 1, name: "Alice", age: 25, department: "Engineering", salary: 75000 },
84
    { id: 2, name: "Bob", age: 30, department: "Engineering", salary: 85000 },
85
    { id: 3, name: "Charlie", age: 28, department: "Sales", salary: 65000 },
86
    { id: 4, name: "Diana", age: 32, department: "Sales", salary: 70000 }
87
  ],
88
  columns: [
89
    { title: "ID", field: "id" },
90
    { title: "Name", field: "name" },
91
    { title: "Age", field: "age" },
92
    { title: "Department", field: "department" },
93
    { title: "Salary", field: "salary", formatter: "money" }
94
  ],
95
  selectableRange: 5, // Allow up to 5 simultaneous ranges
96
  selectableRangeColumns: true, // Enable column range selection
97
  selectableRangeRows: true, // Enable row range selection
98
  selectableRangeClearCells: true, // Allow clearing selected cells
99
  selectableRangeClearCellsValue: "", // Value to use when clearing
100
  selectableRangeAutoFocus: true // Auto-focus after range operations
101
});
102

103
// Programmatically create ranges
104
const startCell = table.getRow(0).getCell("name");
105
const endCell = table.getRow(2).getCell("age");
106
const range = table.addRange(startCell, endCell);
107

108
// Get range data
109
const rangesData = table.getRangesData();
110
console.log("Range data:", rangesData);
111

112
// Get all active ranges
113
const activeRanges = table.getRanges();
114
activeRanges.forEach((range, index) => {
115
  console.log(`Range ${index}:`, range.getData());
116
});
117

118
// Check which ranges include a specific cell
119
const cell = table.getRow(1).getCell("department");
120
const cellRanges = cell.getRanges();
121
console.log(`Cell is in ${cellRanges.length} ranges`);
122
```
123

124
## RangeComponent Class
125

126
Component class representing a selected range with methods for data access and manipulation.
127

128
```javascript { .api }
129
class RangeComponent {
130
  /**
131
   * Get the DOM element representing this range
132
   * @returns Range overlay element
133
   */
134
  getElement(): HTMLElement;
135
  
136
  /**
137
   * Get data from all cells in this range
138
   * @returns Array of arrays representing range data
139
   */
140
  getData(): any[][];
141
  
142
  /**
143
   * Get all cell components in this range
144
   * @returns Array of CellComponent objects
145
   */
146
  getCells(): CellComponent[];
147
  
148
  /**
149
   * Get cells organized by row and column structure
150
   * @returns Object with structured cell data
151
   */
152
  getStructuredCells(): { [row: number]: { [col: number]: CellComponent } };
153
  
154
  /**
155
   * Get all row components that intersect this range
156
   * @returns Array of RowComponent objects
157
   */
158
  getRows(): RowComponent[];
159
  
160
  /**
161
   * Get all column components that intersect this range
162
   * @returns Array of ColumnComponent objects
163
   */
164
  getColumns(): ColumnComponent[];
165
  
166
  /**
167
   * Get range boundary coordinates
168
   * @returns Object with start/end row/column indices
169
   */
170
  getBounds(): RangeBounds;
171
  
172
  /**
173
   * Get top edge row index
174
   * @returns Top row index
175
   */
176
  getTopEdge(): number;
177
  
178
  /**
179
   * Get bottom edge row index  
180
   * @returns Bottom row index
181
   */
182
  getBottomEdge(): number;
183
  
184
  /**
185
   * Get left edge column index
186
   * @returns Left column index
187
   */
188
  getLeftEdge(): number;
189
  
190
  /**
191
   * Get right edge column index
192
   * @returns Right column index
193
   */
194
  getRightEdge(): number;
195
  
196
  /**
197
   * Remove this range from selection
198
   */
199
  remove(): void;
200
}
201
```
202

203
**Advanced Usage Examples:**
204

205
```javascript
206
// Multi-range selection
207
const table = new Tabulator("#table", {
208
  selectableRange: 3, // Allow up to 3 ranges
209
  selectableRangeColumns: true,
210
  selectableRangeRows: true
211
});
212

213
// Create multiple ranges programmatically
214
const range1 = table.addRange(
215
  table.getRow(0).getCell("name"),
216
  table.getRow(2).getCell("age")
217
);
218

219
const range2 = table.addRange(
220
  table.getRow(3).getCell("department"),
221
  table.getRow(4).getCell("salary")
222
);
223

224
// Analyze range contents
225
const ranges = table.getRanges();
226
ranges.forEach((range, index) => {
227
  const bounds = range.getBounds();
228
  const data = range.getData();
229
  const cells = range.getCells();
230
  
231
  console.log(`Range ${index + 1}:`);
232
  console.log(`  Bounds: rows ${bounds.start.row}-${bounds.end.row}, cols ${bounds.start.col}-${bounds.end.col}`);
233
  console.log(`  Contains ${cells.length} cells`);
234
  console.log(`  Data:`, data);
235
  
236
  // Get unique columns in range
237
  const columns = range.getColumns();
238
  console.log(`  Spans ${columns.length} columns:`, columns.map(col => col.getField()));
239
  
240
  // Get rows in range
241
  const rows = range.getRows();
242
  console.log(`  Spans ${rows.length} rows`);
243
});
244

245
// Work with structured cell data
246
const structuredCells = range1.getStructuredCells();
247
Object.keys(structuredCells).forEach(rowIndex => {
248
  Object.keys(structuredCells[rowIndex]).forEach(colIndex => {
249
    const cell = structuredCells[rowIndex][colIndex];
250
    console.log(`Cell [${rowIndex},${colIndex}]: ${cell.getValue()}`);
251
  });
252
});
253
```
254

255
## Range Selection Modes
256

257
Configure different selection behaviors for various use cases.
258

259
**Cell Range Selection:**
260
```javascript
261
const table = new Tabulator("#table", {
262
  selectableRange: true, // Enable basic cell range selection
263
  selectableRangeColumns: false,
264
  selectableRangeRows: false
265
});
266
```
267

268
**Column Range Selection:**
269
```javascript
270
const table = new Tabulator("#table", {
271
  selectableRange: true,
272
  selectableRangeColumns: true, // Enable column selection
273
  selectableRangeRows: false
274
});
275
```
276

277
**Row Range Selection:**
278
```javascript
279
const table = new Tabulator("#table", {
280
  selectableRange: true,  
281
  selectableRangeColumns: false,
282
  selectableRangeRows: true // Enable row selection
283
});
284

285
**Mixed Range Selection:**
286
```javascript
287
const table = new Tabulator("#table", {
288
  selectableRange: 10, // Allow up to 10 ranges
289
  selectableRangeColumns: true, // Enable all selection types
290
  selectableRangeRows: true
291
});
292
```
293

294
## Keyboard Interactions
295

296
Range selection supports standard spreadsheet keyboard shortcuts:
297

298
- **Arrow Keys**: Move active cell within table
299
- **Shift + Arrow Keys**: Extend selection range
300
- **Ctrl/Cmd + A**: Select all cells
301
- **Ctrl/Cmd + Click**: Add new range to selection
302
- **Delete**: Clear contents of selected cells (if enabled)
303
- **Escape**: Clear all selections
304

305
## Clear Cell Functionality
306

307
Configure cell clearing behavior within selected ranges.
308

309
```javascript
310
const table = new Tabulator("#table", {
311
  selectableRange: true,
312
  selectableRangeClearCells: true, // Enable cell clearing
313
  selectableRangeClearCellsValue: null, // Value to use when clearing
314
  // ... other options
315
});
316

317
// Programmatically clear selected ranges
318
document.getElementById("clear-btn").addEventListener("click", () => {
319
  const ranges = table.getRanges();
320
  ranges.forEach(range => {
321
    const cells = range.getCells();
322
    cells.forEach(cell => {
323
      cell.setValue(""); // Clear each cell
324
    });
325
  });
326
});
327
```
328

329
## Events
330

331
Range selection provides events for tracking selection changes.
332

333
```javascript { .api }
334
// Range selection events
335
table.on("rangeAdded", function(range) {
336
  console.log("Range added:", range.getData());
337
});
338

339
table.on("rangeRemoved", function(range) {
340
  console.log("Range removed");
341
});
342

343
table.on("rangeChanged", function(ranges) {
344
  console.log(`Selection changed: ${ranges.length} ranges active`);
345
});
346
```
347

348
## Integration with Other Features
349

350
Range selection integrates with other Tabulator features:
351

352
```javascript
353
// Copy/paste with clipboard module
354
table.on("rangeAdded", function(range) {
355
  // Enable custom copy functionality
356
  document.addEventListener("keydown", function(e) {
357
    if ((e.ctrlKey || e.metaKey) && e.key === "c") {
358
      const data = range.getData();
359
      // Copy data to clipboard
360
      navigator.clipboard.writeText(JSON.stringify(data));
361
    }
362
  });
363
});
364

365
// Export selected ranges
366
document.getElementById("export-btn").addEventListener("click", () => {
367
  const ranges = table.getRanges();
368
  if (ranges.length > 0) {
369
    const rangeData = ranges[0].getData();
370
    table.download("csv", "selected-range.csv", {data: rangeData});
371
  }
372
});
373
```
374

375
## Types
376

377
```javascript { .api }
378
interface RangeBounds {
379
  start: {
380
    row: number;
381
    col: number;
382
  };
383
  end: {
384
    row: number;
385
    col: number;
386
  };
387
}
388

389
interface RangeSelectionOptions {
390
  selectableRange?: boolean | number;
391
  selectableRangeColumns?: boolean;
392
  selectableRangeRows?: boolean;
393
  selectableRangeClearCells?: boolean;
394
  selectableRangeClearCellsValue?: any;
395
  selectableRangeAutoFocus?: boolean;
396
}
397
```