Table Class

The UserTable interface provides the public API for manipulating spreadsheet data programmatically. It offers comprehensive methods for data access, manipulation, and history management.

Overview

The UserTable interface provides access to:

• Cell data retrieval and manipulation
• Row and column operations
• History and undo/redo functionality
• Matrix and object data access
• Cross-sheet communication

Important: When using table methods that return a new UserTable instance (like update, write, setHeaderHeight, etc.), you must call sync() to apply the changes to the GridSheet component. The table instance alone is not sufficient to update the UI.

Core Properties

Data Access Methods

Cell Retrieval

getCellByPoint(point: PointType, refEvaluation?: RefEvaluation, raise?: boolean): CellType | undefined

Retrieves a cell by its coordinates.

const cell = table.getCellByPoint({ x: 1, y: 1 });
console.log(cell?.value, cell?.style);

getCellByAddress(address: Address, refEvaluation?: RefEvaluation, raise?: boolean): CellType | undefined

Retrieves a cell by its address.

const cell = table.getCellByAddress('A1');
console.log(cell?.value);

Matrix and Object Access

getCellMatrix(args?: GetCellMatrix): (CellType | null)[][]

Retrieves cells as a 2D matrix. Supports ignoreFields to exclude specific cell properties.

const matrix = table.getCellMatrix({ area: { top: 0, left: 0, bottom: 2, right: 2 } });
console.log(matrix);

getCellObject(args?: GetCellObject): CellsByAddressType

Retrieves cells as an object with addresses as keys. Supports ignoreFields to exclude specific cell properties.

const cells = table.getCellObject({ refEvaluation: 'COMPLETE' });
console.log(cells);

getCellRows(args?: GetCellRows): CellsByAddressType[]

Retrieves cells organized by rows. Supports ignoreFields to exclude specific cell properties.

const rows = table.getCellRows();
console.log(rows[0]); // First row cells

getCellCols(args?: GetCellCols): CellsByAddressType[]

Retrieves cells organized by columns. Supports ignoreFields to exclude specific cell properties.

const cols = table.getCellCols();
console.log(cols[0]); // First column cells

Field-Specific Access

getFieldMatrix(args?: GetFieldPropsWithArea): any[][]

Retrieves a specific field (e.g., 'value', 'style') as a matrix.

const values = table.getFieldMatrix({ field: 'value' });
const styles = table.getFieldMatrix({ field: 'style' });

getFieldObject(args?: GetFieldProps): { [address: Address]: any }

Retrieves a specific field as an object.

const values = table.getFieldObject({ field: 'value' });

getFieldRows(args?: GetFieldProps): { [address: Address]: any }[]

Retrieves a specific field organized by rows.

const valueRows = table.getFieldRows({ field: 'value' });

getFieldCols(args?: GetFieldProps): { [address: Address]: any }[]

Retrieves a specific field organized by columns.

const valueCols = table.getFieldCols({ field: 'value' });

Data Manipulation Methods

Important: All data manipulation methods return a new UserTable instance. To apply changes to the GridSheet component, you must use the sync function from connector.

Using Table References

To manipulate table data, you need to access the table through a table reference:

React (useConnector)

useConnector is a React hook and must be called within a function component:

import { useConnector, GridSheet } from '@gridsheet/react-core';
 
function MyComponent() {
  const connector = useConnector(); // Must be called inside function component
  
  const handleUpdate = () => {
    if (connector.current) {
      const { tableManager } = connector.current;
      const { table, sync } = tableManager;
      table.write({ point: { x: 1, y: 1 }, value: 'New Value' });
      sync(table);
    }
  };
 
  return (
    <GridSheet connector={connector} initialCells={initialCells} />
  );
}

Global Usage and Other Frameworks (createConnector)

For global usage or non-React frameworks (Vue, Svelte), use createConnector:

import { createConnector, GridSheet } from '@gridsheet/react-core';
 
// Create a connector reference
const connector = createConnector();
 
// Use it in your component
function MyComponent() {
  const connector = createConnector();
  
  return (
    <GridSheet connector={connector} initialCells={initialCells} />
  );
}

Cell Updates

Note: The sync function used in the examples below should be obtained from the connector as shown in the "Using Table References" section above.

update(args: { diff: CellsByAddressType; historicize?: boolean; partial?: boolean; updateChangedTime?: boolean; reflection?: StorePatchType }): UserTable

Updates multiple cells at once.

// Get sync from connector
const { table, sync } = connector.current.tableManager;
 
const newTable = table.update({
  diff: {
    'A1': { value: 'Updated Value' },
    'B1': { style: { color: '#FF0000' } }
  },
  historicize: true
});
sync(newTable); // Required to apply changes

write(args: { point: PointType; value: string; updateChangedTime?: boolean; reflection?: StorePatchType }): UserTable

Writes a value to a specific cell.

// Get sync from connector
const { table, sync } = connector.current.tableManager;
 
const newTable = table.write({
  point: { x: 1, y: 1 },
  value: 'Hello World'
});
sync(newTable); // Required to apply changes

writeMatrix(args: { point: PointType; matrix: MatrixType<string>; updateChangedTime?: boolean; reflection?: StorePatchType }): UserTable

Writes a matrix of values starting at a specific point.

// Get sync from connector
const { table, sync } = connector.current.tableManager;
 
const newTable = table.writeMatrix({
  point: { x: 1, y: 1 },
  matrix: [['A1', 'B1'], ['A2', 'B2']]
});
sync(newTable); // Required to apply changes

Row Operations

insertRows(args: { y: number; numRows: number; baseY: number; diff?: CellsByAddressType; partial?: boolean; updateChangedTime?: boolean; reflection?: StorePatchType }): UserTable

Inserts rows at the specified position. If diff is provided, it also updates the cells after insertion.

// Get sync from connector
const { table, sync } = connector.current.tableManager;
 
const newTable = table.insertRows({
  y: 5,
  numRows: 2,
  baseY: 5,
  diff: {
    A5: { value: 'New Row 1' },
    A6: { value: 'New Row 2' },
  },
});
sync(newTable); // Required to apply changes

removeRows(args: { y: number; numRows: number; reflection?: StorePatchType }): UserTable

Removes rows at a specific position.

// Get sync from connector
const { table, sync } = connector.current.tableManager;
 
const newTable = table.removeRows({
  y: 2,
  numRows: 3
});
sync(newTable); // Required to apply changes

Column Operations

insertCols(args: { x: number; numCols: number; baseX: number; diff?: CellsByAddressType; partial?: boolean; updateChangedTime?: boolean; reflection?: StorePatchType }): UserTable

Inserts columns at the specified position. If diff is provided, it also updates the cells after insertion.

// Get sync from connector
const { table, sync } = connector.current.tableManager;
 
const newTable = table.insertCols({
  x: 3,
  numCols: 2,
  baseX: 3,
  diff: {
    C1: { value: 'New Col 1' },
    D1: { value: 'New Col 2' },
  },
});
sync(newTable); // Required to apply changes

removeCols(args: { x: number; numCols: number; reflection?: StorePatchType }): UserTable

Removes columns at a specific position.

// Get sync from connector
const { table, sync } = connector.current.tableManager;
 
const newTable = table.removeCols({
  x: 2,
  numCols: 3
});
sync(newTable); // Required to apply changes

Move and Copy Operations

move(args: MoveProps): UserTable

Moves cells from one area to another.

// Get sync from connector
const { table, sync } = connector.current.tableManager;
 
const newTable = table.move({
  src: { top: 0, left: 0, bottom: 2, right: 2 },
  dst: { top: 5, left: 5, bottom: 7, right: 7 }
});
sync(newTable); // Required to apply changes

copy(args: MoveProps & { onlyValue?: boolean }): UserTable

Copies cells from one area to another.

// Get sync from connector
const { table, sync } = connector.current.tableManager;
 
const newTable = table.copy({
  src: { top: 0, left: 0, bottom: 2, right: 2 },
  dst: { top: 5, left: 5, bottom: 7, right: 7 },
  onlyValue: false
});
sync(newTable); // Required to apply changes

Sort and Filter Operations

sortRows(args: { x: number; direction: 'asc' | 'desc' }): UserTable

Sorts all data rows by the values in the specified column. Supports ascending and descending order. Null/undefined values are sorted to the end. This operation is recorded in the undo/redo history.

// Get sync from connector
const { table, sync } = connector.current.tableManager;
 
// Sort by column B ascending
const newTable = table.sortRows({ x: 2, direction: 'asc' });
sync(newTable);
 
// Sort by column A descending
const newTable = table.sortRows({ x: 1, direction: 'desc' });
sync(newTable);

filterRows(args?: { x?: number; filter?: FilterConfig }): UserTable

Applies a filter to the specified column. Rows that do not match the filter conditions are hidden. Multiple columns can have independent filters, and they are combined with AND logic across columns. If called without filter, clears the filter for the specified column. If called without x, clears all column filters.

The FilterConfig object has the following structure:

type FilterConfig = {
  mode: 'and' | 'or';        // How multiple conditions are combined
  conditions: FilterCondition[];
};
 
type FilterCondition = {
  method: FilterConditionMethod;  // e.g., 'eq', 'contains', 'gt', etc.
  value: string[];
};

Available filter methods:

// Get sync from connector
const { table, sync } = connector.current.tableManager;
 
// Filter column B: show only rows where value > 80
const newTable = table.filterRows({
  x: 2,
  filter: {
    mode: 'and',
    conditions: [{ method: 'gt', value: ['80'] }],
  },
});
sync(newTable);
 
// Clear filter on column B only
const newTable = table.filterRows({ x: 2 });
sync(newTable);
 
// Clear all filters
const newTable = table.filterRows();
sync(newTable);

isRowFiltered(y: number): boolean

Returns true if the specified row is currently hidden by a filter.

if (table.isRowFiltered(3)) {
  console.log('Row 3 is hidden by a filter');
}

hasActiveFilters(): boolean

Returns true if any column has an active filter.

if (table.hasActiveFilters()) {
  console.log('Some filters are active');
}