Grid Class

Complete reference for the Grid class constructor, methods, and properties.

Grid Class

The Grid class is the main entry point for creating and managing a ZenGrid instance.

Constructor

import { Grid } from '@zengrid/core';

const grid = new Grid(container, options);

Parameters:

• container: HTMLElement - The DOM element that will contain the grid
• options: GridOptions - Configuration options for the grid

Data Methods

setData()

Sets the grid’s data array.

grid.setData([
  ['Alice', 30, 'Engineering'],
  ['Bob', 25, 'Design'],
  ['Charlie', 35, 'Product']
]);

Parameters:

• data: any[][] - Two-dimensional array of cell values

getData()

Gets the value of a specific cell.

const value = grid.getData(row, col);

Parameters:

• row: number - Row index
• col: number - Column index

Returns: The cell value

getDataMode()

Gets the current data mode.

const mode = grid.getDataMode();
// Returns: 'frontend' | 'backend' | 'auto'

Rendering Methods

render()

Renders the grid. Called automatically after initialization.

grid.render();

refresh()

Forces a complete re-render of the grid.

grid.refresh();

clearCache()

Clears the renderer cache.

grid.clearCache();

updateCells()

Updates specific cells efficiently.

grid.updateCells([
  { row: 0, col: 1 },
  { row: 2, col: 3 }
]);

Parameters:

• cells: CellRef[] - Array of cell references to update

destroy()

Destroys the grid instance and cleans up all resources.

grid.destroy();

Scrolling Methods

scrollToCell()

Scrolls to bring a specific cell into view.

grid.scrollToCell(row, col);

Parameters:

• row: number - Target row index
• col: number - Target column index

scrollThroughCells()

Smoothly scrolls through a sequence of cells.

grid.scrollThroughCells(
  [
    { row: 0, col: 0 },
    { row: 5, col: 2 },
    { row: 10, col: 1 }
  ],
  { duration: 500, delay: 200 }
);

Parameters:

• cells: CellRef[] - Array of cells to scroll through
• options?: { duration?: number, delay?: number } - Animation options

getScrollPosition()

Gets the current scroll position.

const { top, left } = grid.getScrollPosition();

Returns: ScrollPosition object with top and left properties

getVisibleRange()

Gets the range of currently visible cells.

const range = grid.getVisibleRange();
// { startRow: 0, endRow: 20, startCol: 0, endCol: 5 }

Returns: VisibleRange object

Sorting Methods

sort()

Sorts the grid by a specific column.

grid.sort(columnIndex, 'asc');

Parameters:

• column: number - Column index to sort by
• direction?: 'asc' | 'desc' | null - Sort direction (defaults to ‘asc’)

toggleSort()

Toggles the sort direction for a column.

grid.toggleSort(columnIndex);

Parameters:

• column: number - Column index to toggle

getSortState()

Gets the current sort state for all columns.

const sortState = grid.getSortState();
// [{ column: 1, direction: 'asc', sortIndex: 0 }]

Returns: Array of SortState objects

getColumnSort()

Gets the sort state for a specific column.

const sortState = grid.getColumnSort(columnIndex);

Parameters:

• column: number - Column index

Returns: SortState object or undefined

getSortIcons()

Gets the configured sort icons.

const icons = grid.getSortIcons();

Returns: Sort icons configuration

getSortMode()

Gets the current sort mode.

const mode = grid.getSortMode();
// Returns: 'frontend' | 'backend' | 'auto'

clearSort()

Clears all sorting.

grid.clearSort();

setSortState()

Sets the sort state for multiple columns.

grid.setSortState([
  { column: 0, direction: 'asc', sortIndex: 0 },
  { column: 2, direction: 'desc', sortIndex: 1 }
]);

Parameters:

• sortState: SortState[] - Array of sort states to apply

Filtering Methods

setFilter()

Sets a simple filter on a column.

grid.setFilter(columnIndex, 'contains', 'search term');

Parameters:

• column: number - Column index
• operator: FilterOperator - Filter operator
• value?: any - Filter value

setColumnFilter()

Sets advanced filter conditions on a column.

grid.setColumnFilter(
  columnIndex,
  [
    { operator: 'greaterThan', value: 10 },
    { operator: 'lessThan', value: 100 }
  ],
  'AND'
);

Parameters:

• column: number - Column index
• conditions: FilterCondition[] - Array of filter conditions
• logic?: 'AND' | 'OR' - Logic operator (defaults to ‘AND’)

getFilterState()

Gets the current filter state.

const filterState = grid.getFilterState();

Returns: Array of FilterModel objects

setFilterState()

Sets the filter state for multiple columns.

grid.setFilterState([
  {
    column: 0,
    conditions: [{ operator: 'equals', value: 'Active' }]
  }
]);

Parameters:

• models: FilterModel[] - Array of filter models

getFieldFilterState()

Gets filter state organized by field names.

const fieldFilters = grid.getFieldFilterState();

Returns: Object mapping field names to filter models

getFilterExports()

Gets filter state in multiple export formats.

const exports = grid.getFilterExports();
// { sql: "...", rest: {...}, graphql: {...}, models: [...] }

Returns: Object with SQL, REST, GraphQL, and model representations

getFilterMode()

Gets the current filter mode.

const mode = grid.getFilterMode();
// Returns: 'frontend' | 'backend' | 'auto'

clearFilters()

Clears all filters.

grid.clearFilters();

clearColumnFilter()

Clears the filter for a specific column.

grid.clearColumnFilter(columnIndex);

Parameters:

• column: number - Column index

setQuickFilter()

Sets a quick search filter across multiple columns.

grid.setQuickFilter('search term', [0, 1, 2]);

Parameters:

• query: string - Search query
• columns?: number[] - Columns to search (defaults to all)

clearQuickFilter()

Clears the quick filter.

grid.clearQuickFilter();

getQuickFilter()

Gets the current quick filter query.

const query = grid.getQuickFilter();

Returns: Current quick filter query string

Export Methods

exportCSV()

Exports grid data as CSV.

const csv = grid.exportCSV({
  rows: 'visible',
  columns: 'all',
  includeHeaders: true
});

Parameters:

• options?: GridExportOptions - Export configuration

Returns: CSV string

exportTSV()

Exports grid data as TSV.

const tsv = grid.exportTSV({
  rows: 'visible',
  columns: 'all',
  includeHeaders: true
});

Parameters:

• options?: GridExportOptions - Export configuration

Returns: TSV string

Pagination Methods

goToPage()

Navigates to a specific page.

grid.goToPage(3);

Parameters:

• page: number - Target page number (1-based)

nextPage()

Navigates to the next page.

grid.nextPage();

previousPage()

Navigates to the previous page.

grid.previousPage();

firstPage()

Navigates to the first page.

grid.firstPage();

lastPage()

Navigates to the last page.

grid.lastPage();

setPageSize()

Sets the number of rows per page.

grid.setPageSize(50);

Parameters:

• pageSize: number - Number of rows per page

getCurrentPage()

Gets the current page number.

const page = grid.getCurrentPage();

Returns: Current page number (1-based)

getPageSize()

Gets the current page size.

const size = grid.getPageSize();

Returns: Number of rows per page

getTotalPages()

Gets the total number of pages.

const total = grid.getTotalPages();

Returns: Total page count

Column Methods

attachColumnResize()

Attaches column resize functionality to a header element.

grid.attachColumnResize(headerElement);

Parameters:

• headerEl: HTMLElement - Header element

detachColumnResize()

Detaches column resize functionality.

grid.detachColumnResize();

resizeColumn()

Programmatically resizes a column.

grid.resizeColumn(columnIndex, 150);

Parameters:

• col: number - Column index
• width: number - New width in pixels

autoFitColumn()

Auto-fits a column to its content.

grid.autoFitColumn(columnIndex);

Parameters:

• col: number - Column index

autoFitAllColumns()

Auto-fits all columns to their content.

grid.autoFitAllColumns();

setColumnConstraints()

Sets width constraints for a column.

grid.setColumnConstraints(columnIndex, {
  minWidth: 100,
  maxWidth: 500
});

Parameters:

• col: number - Column index
• constraints: { minWidth?: number, maxWidth?: number } - Width constraints

attachColumnDrag()

Attaches column drag functionality to a header element.

grid.attachColumnDrag(headerElement);

Parameters:

• headerEl: HTMLElement - Header element

detachColumnDrag()

Detaches column drag functionality.

grid.detachColumnDrag();

isDragging()

Checks if a column is currently being dragged.

const dragging = grid.isDragging();

Returns: Boolean indicating drag state

Header Methods

registerHeaderRenderer()

Registers a custom header renderer.

grid.registerHeaderRenderer('custom', customHeaderRenderer);

Parameters:

• name: string - Renderer name
• renderer: HeaderRenderer - Renderer implementation

updateHeader()

Updates a specific header cell.

grid.updateHeader(columnIndex);

Parameters:

• colIndex: number - Column index

updateAllHeaders()

Updates all header cells.

grid.updateAllHeaders();

refreshHeaders()

Forces a complete refresh of all headers.

grid.refreshHeaders();

State Methods

getColumnState()

Gets the state of all columns.

const state = grid.getColumnState();

Returns: Array of ColumnStateSnapshot objects

applyColumnState()

Applies column state configuration.

grid.applyColumnState(state, { applyOrder: true });

Parameters:

• state: ColumnStateSnapshot[] - Column state to apply
• options?: { applyOrder?: boolean } - Application options

getStateSnapshot()

Gets a complete snapshot of the grid state.

const snapshot = grid.getStateSnapshot();

Returns: GridStateSnapshot object

applyStateSnapshot()

Restores the grid from a state snapshot.

grid.applyStateSnapshot(snapshot);

Parameters:

• snapshot: GridStateSnapshot - State snapshot to restore

Event Methods

on()

Registers an event listener.

grid.on('cell:click', (event) => {
  console.log('Cell clicked:', event.cell);
});

Parameters:

• event: string - Event name
• handler: Function - Event handler function

Returns: Cleanup function to unregister the listener

off()

Unregisters an event listener.

grid.off('cell:click', handler);

Parameters:

• event: string - Event name
• handler: Function - Event handler function to remove

Configuration Methods

registerRenderer()

Registers a custom cell renderer.

grid.registerRenderer('custom', customRenderer);

Parameters:

• name: string - Renderer name
• renderer: CellRenderer - Renderer implementation

updateOptions()

Updates grid options at runtime.

grid.updateOptions({
  rowHeight: 40,
  enableSelection: true
});

Parameters:

• options: Partial<GridOptions> - Options to update

getStats()

Gets performance and usage statistics.

const stats = grid.getStats();

Returns: Object with grid statistics

getDimensions()

Gets the grid’s current dimensions.

const { width, height } = grid.getDimensions();

Returns: Object with width and height properties

getColumnPosition()

Gets the visual position of a column.

const position = grid.getColumnPosition(columnIndex);
// { x: 150, width: 100 }

Parameters:

• col: number - Column index

Returns: Object with x and width properties

Plugin Methods

getStore()

Gets the internal reactive store.

const store = grid.getStore();

Returns: The grid’s reactive store instance

getPluginHost()

Gets the plugin host for advanced plugin management.

const pluginHost = grid.getPluginHost();

Returns: The plugin host instance

getGridApi()

Gets the grid API object.

const api = grid.getGridApi();

Returns: The grid API instance

usePlugin()

Registers and activates a plugin.

grid.usePlugin(customPlugin);

Parameters:

• plugin: GridPlugin - Plugin to register

Infinite Scroll Methods

resetInfiniteScrolling()

Resets the infinite scrolling state.

grid.resetInfiniteScrolling();

getSlidingWindowStats()

Gets statistics about the sliding window for infinite scroll.

const stats = grid.getSlidingWindowStats();
// { windowSize: 1000, prunedRows: 500, totalLoaded: 5000 }

Returns: Object with sliding window statistics