0
# Core Grid Component
1
2
The `<revo-grid>` component is the main entry point for creating data grids with @revolist/revogrid. It provides a comprehensive set of properties, methods, and events for configuring and controlling grid behavior.
3
4
## Installation and Setup
5
6
```typescript
7
import '@revolist/revogrid';
8
// Or with framework specific wrapper
9
import { RevoGrid } from '@revolist/react-datagrid';
10
```
11
12
## Basic Usage
13
14
```html
15
<revo-grid
16
source="[{name: 'John', age: 30}, {name: 'Jane', age: 25}]"
17
columns="[{prop: 'name', name: 'Name'}, {prop: 'age', name: 'Age'}]">
18
</revo-grid>
19
```
20
21
## Properties
22
23
### Data Properties
24
25
Configure the primary data sources for your grid:
26
27
```typescript { .api }
28
interface DataProperties {
29
source: RevoGrid.DataType[];
30
pinnedTopSource: RevoGrid.DataType[];
31
pinnedBottomSource: RevoGrid.DataType[];
32
columns: (RevoGrid.ColumnRegular | RevoGrid.ColumnGrouping)[];
33
}
34
```
35
36
**source** { .api }
37
```typescript
38
source: RevoGrid.DataType[]
39
```
40
Main data source containing an array of objects or 2D array. Each object represents a row with properties matching column definitions.
41
42
**pinnedTopSource** { .api }
43
```typescript
44
pinnedTopSource: RevoGrid.DataType[]
45
```
46
Data source for rows pinned to the top of the grid. These rows remain visible when scrolling vertically.
47
48
**pinnedBottomSource** { .api }
49
```typescript
50
pinnedBottomSource: RevoGrid.DataType[]
51
```
52
Data source for rows pinned to the bottom of the grid. These rows remain visible when scrolling vertically.
53
54
**columns** { .api }
55
```typescript
56
columns: (RevoGrid.ColumnRegular | RevoGrid.ColumnGrouping)[]
57
```
58
Array of column definitions that can include regular columns or grouped columns. See [Column System](./column-system.md) for details.
59
60
### Display Properties
61
62
Control visual appearance and layout:
63
64
```typescript { .api }
65
interface DisplayProperties {
66
rowHeaders: RevoGrid.RowHeaders | boolean;
67
frameSize: number;
68
rowSize: number;
69
colSize: number;
70
theme: ThemeSpace.Theme;
71
rowClass: string;
72
}
73
```
74
75
**rowHeaders** { .api }
76
```typescript
77
rowHeaders: RevoGrid.RowHeaders | boolean = false
78
```
79
Show Excel-like row index headers. When `true`, displays sequential row numbers. Can be configured with custom row header options.
80
81
**frameSize** { .api }
82
```typescript
83
frameSize: number = 1
84
```
85
Number of rows/columns rendered outside the visible area for smoother scrolling. Higher values improve scrolling performance but increase memory usage.
86
87
**rowSize** { .api }
88
```typescript
89
rowSize: number = 0
90
```
91
Default row height in pixels. When `0`, uses the theme's default row height.
92
93
**colSize** { .api }
94
```typescript
95
colSize: number = 100
96
```
97
Default column width in pixels applied to columns without explicit width settings.
98
99
**theme** { .api }
100
```typescript
101
theme: ThemeSpace.Theme = 'default'
102
```
103
Theme name. Available themes: `'default' | 'material' | 'compact' | 'darkMaterial' | 'darkCompact'`.
104
105
**rowClass** { .api }
106
```typescript
107
rowClass: string = ''
108
```
109
CSS class property name in row objects that will be applied as CSS class to the row element.
110
111
### Interaction Properties
112
113
Configure user interaction capabilities:
114
115
```typescript { .api }
116
interface InteractionProperties {
117
range: boolean;
118
readonly: boolean;
119
resize: boolean;
120
canFocus: boolean;
121
useClipboard: boolean;
122
canMoveColumns: boolean;
123
}
124
```
125
126
**range** { .api }
127
```typescript
128
range: boolean = false
129
```
130
Enable range selection functionality. Users can select multiple cells by dragging or using Shift+Click.
131
132
**readonly** { .api }
133
```typescript
134
readonly: boolean = false
135
```
136
Put grid in read-only mode. Users cannot edit cell values when enabled.
137
138
**resize** { .api }
139
```typescript
140
resize: boolean = false
141
```
142
Enable column resizing. Users can drag column borders to adjust width.
143
144
**canFocus** { .api }
145
```typescript
146
canFocus: boolean = true
147
```
148
Enable cell focus functionality. Shows focus border around active cell.
149
150
**useClipboard** { .api }
151
```typescript
152
useClipboard: boolean = true
153
```
154
Enable clipboard operations (copy/paste) with keyboard shortcuts.
155
156
**canMoveColumns** { .api }
157
```typescript
158
canMoveColumns: boolean = false
159
```
160
Enable column drag and drop reordering functionality.
161
162
### Advanced Properties
163
164
Configure advanced features and customizations:
165
166
```typescript { .api }
167
interface AdvancedProperties {
168
editors: Edition.Editors;
169
columnTypes: {[name: string]: RevoGrid.ColumnType};
170
rowDefinitions: RevoGrid.RowDefinition[];
171
plugins: RevoPlugin.PluginClass[];
172
trimmedRows: Record<number, boolean>;
173
grouping: GroupingOptions;
174
stretch: boolean | string;
175
}
176
```
177
178
**editors** { .api }
179
```typescript
180
editors: Edition.Editors = {}
181
```
182
Registry of custom cell editors. Keys are editor names, values are editor constructors.
183
184
**columnTypes** { .api }
185
```typescript
186
columnTypes: {[name: string]: RevoGrid.ColumnType} = {}
187
```
188
Reusable column type definitions that can be referenced in column configs.
189
190
**rowDefinitions** { .api }
191
```typescript
192
rowDefinitions: RevoGrid.RowDefinition[] = []
193
```
194
Array of row property definitions for customizing row behavior and appearance.
195
196
**plugins** { .api }
197
```typescript
198
plugins: RevoPlugin.PluginClass[]
199
```
200
Array of custom plugin classes. Must be defined during initial grid setup.
201
202
**trimmedRows** { .api }
203
```typescript
204
trimmedRows: Record<number, boolean> = {}
205
```
206
Object mapping row indices to boolean values indicating which rows should be hidden.
207
208
**grouping** { .api }
209
```typescript
210
grouping: GroupingOptions
211
```
212
Configuration for row grouping functionality. See [Plugin System](./plugin-system.md) for details.
213
214
**stretch** { .api }
215
```typescript
216
stretch: boolean | string = true
217
```
218
Column stretching strategy. `true` stretches to fill container, `false` disables stretching, or string for specific strategy.
219
220
### Plugin Properties
221
222
Configure built-in plugin features:
223
224
```typescript { .api }
225
interface PluginProperties {
226
autoSizeColumn: boolean | AutoSizeColumnConfig;
227
filter: boolean | ColumnFilterConfig;
228
exporting: boolean;
229
}
230
```
231
232
**autoSizeColumn** { .api }
233
```typescript
234
autoSizeColumn: boolean | AutoSizeColumnConfig = false
235
```
236
Enable automatic column sizing. `true` for default behavior, or object for custom configuration.
237
238
**filter** { .api }
239
```typescript
240
filter: boolean | ColumnFilterConfig = false
241
```
242
Enable column filtering. `true` for default filters, or object for custom filter configuration.
243
244
**exporting** { .api }
245
```typescript
246
exporting: boolean = false
247
```
248
Enable data export functionality with built-in export options.
249
250
## Methods
251
252
### Data Access Methods
253
254
Methods for accessing and manipulating grid data:
255
256
**getSource** { .api }
257
```typescript
258
async getSource(type?: RevoGrid.DimensionRows): Promise<RevoGrid.DataType[]>
259
```
260
Get the data source for a specific row dimension type.
261
262
- **type**: Row dimension type (`'rgRow'`, `'rowPinStart'`, `'rowPinEnd'`)
263
- **Returns**: Promise resolving to array of row data objects
264
265
**getVisibleSource** { .api }
266
```typescript
267
async getVisibleSource(type?: RevoGrid.DimensionRows): Promise<any[]>
268
```
269
Get visible data excluding trimmed or filtered rows.
270
271
- **type**: Row dimension type
272
- **Returns**: Promise resolving to filtered array of visible row data
273
274
**getColumns** { .api }
275
```typescript
276
async getColumns(): Promise<RevoGrid.ColumnRegular[]>
277
```
278
Get all columns configuration.
279
280
- **Returns**: Promise resolving to array of column definitions
281
282
**updateColumns** { .api }
283
```typescript
284
async updateColumns(cols: RevoGrid.ColumnRegular[]): Promise<void>
285
```
286
Update the columns configuration.
287
288
- **cols**: Array of new column definitions
289
290
**getSourceStore** { .api }
291
```typescript
292
async getSourceStore(type?: RevoGrid.DimensionRows): Promise<RowSource>
293
```
294
Access the row store for direct data manipulation.
295
296
- **type**: Row dimension type
297
- **Returns**: Promise resolving to row source store
298
299
**getColumnStore** { .api }
300
```typescript
301
async getColumnStore(type?: RevoGrid.DimensionCols): Promise<ColumnSource>
302
```
303
Access the column store for direct column manipulation.
304
305
- **type**: Column dimension type
306
- **Returns**: Promise resolving to column source store
307
308
### Navigation Methods
309
310
Methods for controlling viewport and focus:
311
312
**scrollToRow** { .api }
313
```typescript
314
async scrollToRow(coordinate?: number): Promise<void>
315
```
316
Scroll to a specific row index.
317
318
- **coordinate**: Row index to scroll to
319
320
**scrollToColumnIndex** { .api }
321
```typescript
322
async scrollToColumnIndex(coordinate?: number): Promise<void>
323
```
324
Scroll to a specific column index.
325
326
- **coordinate**: Column index to scroll to
327
328
**scrollToColumnProp** { .api }
329
```typescript
330
async scrollToColumnProp(prop: RevoGrid.ColumnProp): Promise<void>
331
```
332
Scroll to a column by its property name.
333
334
- **prop**: Column property identifier
335
336
**scrollToCoordinate** { .api }
337
```typescript
338
async scrollToCoordinate(cell: Partial<Selection.Cell>): Promise<void>
339
```
340
Scroll to a specific cell coordinate.
341
342
- **cell**: Cell position object with x and y coordinates
343
344
### Focus Methods
345
346
Methods for managing cell focus and selection:
347
348
**setCellsFocus** { .api }
349
```typescript
350
async setCellsFocus(
351
cellStart?: Selection.Cell,
352
cellEnd?: Selection.Cell,
353
colType?: string,
354
rowType?: string
355
): Promise<void>
356
```
357
Set focus range between two cells.
358
359
- **cellStart**: Starting cell position
360
- **cellEnd**: Ending cell position (for range selection)
361
- **colType**: Column dimension type
362
- **rowType**: Row dimension type
363
364
**getFocused** { .api }
365
```typescript
366
async getFocused(): Promise<FocusedData|null>
367
```
368
Get currently focused cell information.
369
370
- **Returns**: Promise resolving to focused cell data or null
371
372
**clearFocus** { .api }
373
```typescript
374
async clearFocus(): Promise<void>
375
```
376
Clear current cell focus.
377
378
**getSelectedRange** { .api }
379
```typescript
380
async getSelectedRange(): Promise<Selection.RangeArea|null>
381
```
382
Get current selection range.
383
384
- **Returns**: Promise resolving to selection range area or null
385
386
### Editing Methods
387
388
Methods for controlling cell editing:
389
390
**setCellEdit** { .api }
391
```typescript
392
async setCellEdit(
393
rgRow: number,
394
prop: RevoGrid.ColumnProp,
395
rowSource?: RevoGrid.DimensionRows
396
): Promise<void>
397
```
398
Enter edit mode for a specific cell.
399
400
- **rgRow**: Row index
401
- **prop**: Column property
402
- **rowSource**: Row dimension type
403
404
### Sorting Methods
405
406
Methods for controlling data sorting:
407
408
**updateColumnSorting** { .api }
409
```typescript
410
async updateColumnSorting(
411
column: RevoGrid.ColumnRegular,
412
index: number,
413
order: 'asc'|'desc',
414
additive: boolean
415
): Promise<RevoGrid.ColumnRegular>
416
```
417
Update column sorting configuration.
418
419
- **column**: Column definition to sort
420
- **index**: Column index
421
- **order**: Sort order direction
422
- **additive**: Whether to add to existing sort or replace
423
- **Returns**: Updated column definition
424
425
**clearSorting** { .api }
426
```typescript
427
async clearSorting(): Promise<void>
428
```
429
Clear all column sorting.
430
431
### Data Management Methods
432
433
Methods for refreshing and updating grid state:
434
435
**refresh** { .api }
436
```typescript
437
async refresh(type?: RevoGrid.DimensionRows | 'all'): Promise<void>
438
```
439
Refresh the grid viewport and data.
440
441
- **type**: Specific dimension to refresh or 'all' for complete refresh
442
443
**addTrimmed** { .api }
444
```typescript
445
async addTrimmed(
446
trimmed: Record<number, boolean>,
447
trimmedType?: string,
448
type?: RevoGrid.DimensionRows
449
): Promise<CustomEvent>
450
```
451
Add rows to the trimmed (hidden) rows collection.
452
453
- **trimmed**: Object mapping row indices to boolean values
454
- **trimmedType**: Type of trimming operation
455
- **type**: Row dimension type
456
- **Returns**: Promise resolving to custom event
457
458
### Plugin Methods
459
460
Methods for plugin system interaction:
461
462
**getPlugins** { .api }
463
```typescript
464
async getPlugins(): Promise<RevoPlugin.Plugin[]>
465
```
466
Get array of active plugin instances.
467
468
- **Returns**: Promise resolving to active plugins
469
470
**registerVNode** { .api }
471
```typescript
472
async registerVNode(elements: VNode[]): Promise<void>
473
```
474
Register virtual DOM nodes with the grid.
475
476
- **elements**: Array of VNode elements to register
477
478
## Type Definitions
479
480
Core types used in grid configuration:
481
482
```typescript { .api }
483
namespace RevoGrid {
484
type DataType = {[T in ColumnProp]: any};
485
type DataSource = DataType[];
486
type ColumnProp = string | number;
487
488
// Dimension types
489
type DimensionRows = 'rgRow' | 'rowPinStart' | 'rowPinEnd';
490
type DimensionCols = 'colPinStart' | 'rgCol' | 'colPinEnd';
491
492
// Row headers configuration
493
interface RowHeaders {
494
size?: number;
495
rowHeaderColumn?: ColumnRegular;
496
}
497
498
// Row definition for custom row properties
499
interface RowDefinition {
500
type: DimensionRows;
501
index: number;
502
size?: number;
503
[key: string]: any;
504
}
505
}
506
```
507
508
```typescript { .api }
509
namespace ThemeSpace {
510
type Theme = 'default' | 'material' | 'compact' | 'darkMaterial' | 'darkCompact';
511
512
interface ThemePackage {
513
defaultRowSize: number;
514
}
515
516
interface ThemeConfig {
517
rowSize: number;
518
}
519
}
520
```
521
522
## Usage Examples
523
524
### Basic Grid Setup
525
526
```typescript
527
const grid = document.querySelector('revo-grid');
528
529
// Configure basic data grid
530
grid.source = [
531
{ id: 1, name: 'John Doe', age: 30, email: 'john@example.com' },
532
{ id: 2, name: 'Jane Smith', age: 25, email: 'jane@example.com' }
533
];
534
535
grid.columns = [
536
{ prop: 'id', name: 'ID', size: 80 },
537
{ prop: 'name', name: 'Name', size: 150 },
538
{ prop: 'age', name: 'Age', size: 80 },
539
{ prop: 'email', name: 'Email', size: 200 }
540
];
541
```
542
543
### Advanced Configuration
544
545
```typescript
546
// Configure grid with advanced features
547
grid.range = true;
548
grid.resize = true;
549
grid.canMoveColumns = true;
550
grid.theme = 'material';
551
grid.frameSize = 3;
552
553
// Add pinned rows
554
grid.pinnedTopSource = [
555
{ id: 'total', name: 'Total', age: '', email: 'Summary Row' }
556
];
557
558
// Configure row grouping
559
grid.grouping = {
560
props: ['department'],
561
expandedAll: true
562
};
563
564
// Enable plugins
565
grid.autoSizeColumn = true;
566
grid.filter = true;
567
grid.exporting = true;
568
```
569
570
### Accessing Data Programmatically
571
572
```typescript
573
// Get current data
574
const currentData = await grid.getSource();
575
console.log('Current data:', currentData);
576
577
// Get visible data (excluding filtered/trimmed)
578
const visibleData = await grid.getVisibleSource();
579
console.log('Visible data:', visibleData);
580
581
// Navigate to specific cell
582
await grid.scrollToCoordinate({ x: 2, y: 10 });
583
584
// Set focus on a cell range
585
await grid.setCellsFocus(
586
{ x: 0, y: 0 }, // Start cell
587
{ x: 2, y: 5 } // End cell
588
);
589
590
// Get current selection
591
const selection = await grid.getSelectedRange();
592
if (selection) {
593
console.log('Selected range:', selection);
594
}
595
```
596
597
### Working with Stores
598
599
```typescript
600
// Access row store for direct manipulation
601
const rowStore = await grid.getSourceStore();
602
// Row store provides reactive data access
603
604
// Access column store
605
const columnStore = await grid.getColumnStore();
606
// Column store provides column configuration access
607
608
// Refresh specific dimension
609
await grid.refresh('rgRow');
610
611
// Refresh entire grid
612
await grid.refresh('all');
613
```
614
615
The core grid component provides a comprehensive foundation for building data-rich applications with extensive customization options and programmatic control over all aspects of grid behavior.