Types

Key TypeScript types and interfaces used throughout the ZenGrid API.

ZenGrid is written in TypeScript and exports all its types for use in your application.

Column Types

ColumnDef

Defines the configuration for a column.

interface ColumnDef {
  id?: string;
  field: string;
  header: string;
  width?: number;
  renderer?: string | CellRenderer;
  sortable?: boolean;
  editable?: boolean;
  editor?: string | CellEditor;
  editorOptions?: Record<string, any>;
  filterable?: boolean;
  resizable?: boolean;
  reorderable?: boolean;
  minWidth?: number;
  maxWidth?: number;
  overflow?: 'ellipsis' | 'clip' | 'wrap';
  autoHeight?: boolean;
}

Properties:

• id?: string - Unique column identifier (defaults to field name)
• field: string - Field name in data object
• header: string - Header text
• width?: number - Column width in pixels
• renderer?: string | CellRenderer - Custom cell renderer
• sortable?: boolean - Enable sorting (default: true)
• editable?: boolean - Enable editing (default: false)
• editor?: string | CellEditor - Custom cell editor
• editorOptions?: Record<string, any> - Editor configuration
• filterable?: boolean - Enable filtering (default: true)
• resizable?: boolean - Enable resizing (default: true)
• reorderable?: boolean - Enable reordering (default: true)
• minWidth?: number - Minimum column width
• maxWidth?: number - Maximum column width
• overflow?: 'ellipsis' | 'clip' | 'wrap' - Cell overflow behavior
• autoHeight?: boolean - Auto-calculate row height based on content

const columns: ColumnDef[] = [
  {
    field: 'name',
    header: 'Full Name',
    width: 200,
    sortable: true,
    editable: true
  },
  {
    field: 'email',
    header: 'Email Address',
    width: 250,
    renderer: 'link'
  }
];

Cell Types

CellRef

Reference to a specific cell by row and column index.

interface CellRef {
  row: number;
  col: number;
}

const cell: CellRef = { row: 5, col: 2 };
grid.scrollToCell(cell.row, cell.col);

CellRange

Defines a rectangular range of cells.

interface CellRange {
  startRow: number;
  startCol: number;
  endRow: number;
  endCol: number;
}

const range: CellRange = {
  startRow: 0,
  startCol: 0,
  endRow: 10,
  endCol: 5
};

CellPosition

Describes the visual position of a cell in the grid.

interface CellPosition {
  x: number;
  y: number;
  width: number;
  height: number;
}

Properties:

• x: number - Left offset in pixels
• y: number - Top offset in pixels
• width: number - Cell width in pixels
• height: number - Cell height in pixels

Viewport Types

VisibleRange

Range of currently visible cells.

interface VisibleRange {
  startRow: number;
  endRow: number;
  startCol: number;
  endCol: number;
}

const visibleRange = grid.getVisibleRange();
console.log('Visible rows:', visibleRange.startRow, 'to', visibleRange.endRow);

ScrollPosition

Current scroll position of the grid.

interface ScrollPosition {
  top: number;
  left: number;
}

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

Sort Types

SortState

Describes the sort state for a column.

interface SortState {
  column: number;
  direction: 'asc' | 'desc' | null;
  sortIndex?: number;
}

Properties:

• column: number - Column index
• direction: 'asc' | 'desc' | null - Sort direction
• sortIndex?: number - Sort priority for multi-column sorting (0 is highest priority)

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

SortDirection

Sort direction type.

type SortDirection = 'asc' | 'desc' | null;

• 'asc' - Ascending order
• 'desc' - Descending order
• null - No sort

Filter Types

FilterModel

Describes the filter state for a column.

interface FilterModel {
  column: number;
  conditions: FilterCondition[];
  logic?: 'AND' | 'OR';
}

Properties:

• column: number - Column index
• conditions: FilterCondition[] - Array of filter conditions
• logic?: 'AND' | 'OR' - Logical operator for multiple conditions (default: 'AND')

const filterModel: FilterModel = {
  column: 1,
  conditions: [
    { operator: 'greaterThan', value: 10 },
    { operator: 'lessThan', value: 100 }
  ],
  logic: 'AND'
};

FilterCondition

Single filter condition.

interface FilterCondition {
  operator: FilterOperator;
  value?: any;
}

Properties:

• operator: FilterOperator - Comparison operator
• value?: any - Comparison value (not required for operators like isEmpty)

FilterOperator

Available filter operators.

type FilterOperator =
  | 'equals'
  | 'notEquals'
  | 'contains'
  | 'notContains'
  | 'startsWith'
  | 'endsWith'
  | 'isEmpty'
  | 'isNotEmpty'
  | 'greaterThan'
  | 'greaterThanOrEqual'
  | 'lessThan'
  | 'lessThanOrEqual'
  | 'inRange'
  | 'between'
  | 'isNull'
  | 'isNotNull';

Operators:

• equals - Value equals
• notEquals - Value does not equal
• contains - Text contains substring
• notContains - Text does not contain substring
• startsWith - Text starts with
• endsWith - Text ends with
• isEmpty - Value is empty string
• isNotEmpty - Value is not empty string
• greaterThan - Numeric greater than
• greaterThanOrEqual - Numeric greater than or equal
• lessThan - Numeric less than
• lessThanOrEqual - Numeric less than or equal
• inRange - Value in specified range
• between - Alias for inRange
• isNull - Value is null/undefined
• isNotNull - Value is not null/undefined

FilterQuery

SQL-like input format for parsing filter state.

interface FilterQuery {
  sql: string;
  params?: any[];
}

Properties:

• sql: string - SQL-like WHERE expression provided by the caller
• params?: any[] - Parameterized values used during parsing

const query: FilterQuery = {
  sql: 'age > ? AND age < ?',
  params: [10, 100]
};

FilterExpression

Complete filter expression with a canonical AST plus compatibility projections.

interface FilterExpression {
  ast?: FilterAst | null;
  type: 'sql' | 'model';
  sql?: string;
  boundSql?: string;
  params?: any[];
  models?: FilterModel[];
  quickFilter?: FilterQuickState;
  fieldState?: FieldFilterState | null;
  filterExport?: FilterExportResult | null;
}

Properties:

• ast?: FilterAst | null - Canonical typed filter tree used by core
• type: 'sql' | 'model' - Original input type
• sql?: string - Original SQL-like expression, when provided
• boundSql?: string - SQL with positional placeholders
• params?: any[] - Parameterized values
• models?: FilterModel[] - Column-model projection when representable
• quickFilter?: FilterQuickState - Quick filter state
• fieldState?: FieldFilterState | null - Field-oriented backend projection
• filterExport?: FilterExportResult | null - Prebuilt REST / GraphQL / SQL exports

FilterAst

Structured filter tree used by core state, frontend execution, and backend requests.

interface FilterAst {
  version: 1;
  root: FilterAstGroupNode | null;
}

Properties:

• version: 1 - Current AST schema version
• root: FilterAstGroupNode | null - Root group node, or null when no structured filter is active

FilterAstTarget

Shared target reference for AST predicates and search nodes.

type FilterAstTarget =
  | { field: string; column?: number; columnId?: string }
  | { field?: string; column: number; columnId?: string }
  | { field?: string; column?: number; columnId: string };

Notes:

• At least one of field, column, or columnId must be present
• field is the preferred public identifier
• column remains available for index-based compatibility

QueryPaginationState

Pagination slice embedded in backend query requests.

interface QueryPaginationState {
  page: number;
  pageSize: number;
  offset: number;
  cursor?: string | null;
}

QueryState

Canonical backend query envelope used by onDataRequest.

interface QueryState {
  version: 1;
  filter?: FilterAst | null;
  sort?: SortDescriptor[] | null;
  pagination?: QueryPaginationState | null;
}

Notes:

• Query slices may be omitted when inactive
• Slices may also be present with null values when a caller wants to be explicit
• In dataMode: 'auto', ZenGrid typically only populates the pagination/range slice because sort and filter still execute in the browser

Pagination Types

PaginationConfig

Pagination configuration options.

interface PaginationConfig {
  enabled: boolean;
  pageSize: number;
  template: string;
  position: 'top' | 'bottom' | 'both';
  pageSizes: number[];
}

Properties:

• enabled: boolean - Enable pagination
• pageSize: number - Rows per page
• template: string - Display template (e.g., 'Page {current} of {total}')
• position: 'top' | 'bottom' | 'both' - Pagination controls position
• pageSizes: number[] - Available page size options

PaginationState

Current pagination state.

interface PaginationState {
  currentPage: number;
  pageSize: number;
  totalRows: number;
  totalPages: number;
  startRow: number;
  endRow: number;
}

Properties:

• currentPage: number - Current page (1-based)
• pageSize: number - Rows per page
• totalRows: number - Total number of rows
• totalPages: number - Total number of pages
• startRow: number - First row index on current page
• endRow: number - Last row index on current page

State Types

GridStateSnapshot

Complete snapshot of grid state for save/restore.

interface GridStateSnapshot {
  columns: ColumnStateSnapshot[];
  sort: SortState[];
  filter: FilterModel[];
  pagination?: PaginationState;
  scroll?: ScrollPosition;
  selection?: CellRange[];
}

Properties:

• columns: ColumnStateSnapshot[] - Column states
• sort: SortState[] - Sort state
• filter: FilterModel[] - Filter state
• pagination?: PaginationState - Pagination state
• scroll?: ScrollPosition - Scroll position
• selection?: CellRange[] - Selection ranges

// Save state
const snapshot = grid.getStateSnapshot();
localStorage.setItem('gridState', JSON.stringify(snapshot));

// Restore state
const saved = JSON.parse(localStorage.getItem('gridState'));
grid.applyStateSnapshot(saved);

ColumnStateSnapshot

State snapshot for a single column.

interface ColumnStateSnapshot {
  colId: string;
  width?: number;
  visible?: boolean;
  pinned?: 'left' | 'right' | null;
  sort?: SortState;
  filter?: FilterModel;
  order?: number;
}

Properties:

• colId: string - Column identifier
• width?: number - Column width
• visible?: boolean - Visibility state
• pinned?: 'left' | 'right' | null - Pin state
• sort?: SortState - Sort state
• filter?: FilterModel - Filter state
• order?: number - Display order

Export Types

GridExportOptions

Options for exporting grid data.

interface GridExportOptions {
  rows: 'all' | 'visible' | 'selected';
  columns: 'all' | 'visible';
  includeHeaders: boolean;
}

Properties:

• rows: 'all' | 'visible' | 'selected' - Which rows to export
• columns: 'all' | 'visible' - Which columns to export
• includeHeaders: boolean - Include column headers

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

Renderer Types

CellRenderer

Interface for custom cell renderers.

interface CellRenderer {
  render(params: RenderParams): HTMLElement;
  update?(params: RenderParams): void;
  destroy?(element: HTMLElement): void;
  getCellClass?(params: RenderParams): string;
}

Methods:

• render(params): HTMLElement - Create and return the cell element
• update?(params): void - Update existing cell element (optional)
• destroy?(element): void - Clean up when cell is destroyed (optional)
• getCellClass?(params): string - Return CSS class names for the cell (optional)

RenderParams

Parameters passed to cell renderers.

interface RenderParams {
  cell: CellRef;
  position: CellPosition;
  value: any;
  column?: ColumnDef;
  rowData?: any;
  isSelected: boolean;
  isActive: boolean;
  isEditing: boolean;
}

Properties:

• cell: CellRef - Cell coordinates
• position: CellPosition - Visual position
• value: any - Cell value
• column?: ColumnDef - Column definition
• rowData?: any - Full row data object
• isSelected: boolean - Selection state
• isActive: boolean - Active (focused) state
• isEditing: boolean - Editing state

const customRenderer: CellRenderer = {
  render(params) {
    const div = document.createElement('div');
    div.textContent = params.value;
    if (params.isSelected) {
      div.classList.add('selected');
    }
    return div;
  },
  update(params) {
    const div = params.element;
    div.textContent = params.value;
  }
};

Editor Types

CellEditor

Interface for custom cell editors.

interface CellEditor {
  init(params: EditorParams): HTMLElement;
  getValue(): any;
  focus(): void;
  destroy(): void;
  isValid?(): boolean;
  onKeyDown?(event: KeyboardEvent): void;
}

Methods:

• init(params): HTMLElement - Create and return the editor element
• getValue(): any - Get the current editor value
• focus(): void - Focus the editor
• destroy(): void - Clean up when editor is closed
• isValid?(): boolean - Validate current value (optional)
• onKeyDown?(event): void - Handle keyboard events (optional)

EditorParams

Parameters passed to cell editors.

interface EditorParams {
  cell: CellRef;
  column?: ColumnDef;
  rowData?: any;
  onComplete?: (value: any) => void;
  onChange?: (value: any) => void;
  options?: Record<string, any>;
  registerPopup?: (element: HTMLElement) => void;
  unregisterPopup?: (element: HTMLElement) => void;
}

Properties:

• cell: CellRef - Cell being edited
• column?: ColumnDef - Column definition
• rowData?: any - Full row data
• onComplete?: (value) => void - Callback when editing completes
• onChange?: (value) => void - Callback when value changes
• options?: Record<string, any> - Editor-specific options
• registerPopup?: (element) => void - Register popup element (for dropdowns)
• unregisterPopup?: (element) => void - Unregister popup element

const customEditor: CellEditor = {
  init(params) {
    const input = document.createElement('input');
    input.type = 'text';
    input.value = params.value || '';
    input.addEventListener('change', () => {
      params.onChange?.(input.value);
    });
    return input;
  },
  getValue() {
    return this.input.value;
  },
  focus() {
    this.input.focus();
  },
  destroy() {
    // Cleanup
  }
};

Header Renderer Types

HeaderRenderer

Interface for custom header renderers.

interface HeaderRenderer {
  render(params: HeaderRenderParams): HTMLElement;
  update?(params: HeaderRenderParams): void;
  destroy?(element: HTMLElement): void;
  getHeaderClass?(params: HeaderRenderParams): string;
}

Methods:

• render(params): HTMLElement - Create and return the header element
• update?(params): void - Update existing header element (optional)
• destroy?(element): void - Clean up when header is destroyed (optional)
• getHeaderClass?(params): string - Return CSS class names (optional)

HeaderRenderParams

Parameters passed to header renderers.

interface HeaderRenderParams {
  columnIndex: number;
  column?: ColumnDef;
  config: any;
  width: number;
  height: number;
  isHovered?: boolean;
  isFocused?: boolean;
  isResizing?: boolean;
  emit?: (event: string, data?: any) => void;
}

Properties:

• columnIndex: number - Column index
• column?: ColumnDef - Column definition
• config: any - Header configuration
• width: number - Header width
• height: number - Header height
• isHovered?: boolean - Hover state
• isFocused?: boolean - Focus state
• isResizing?: boolean - Resize state
• emit?: (event, data) => void - Event emitter

Plugin Types

GridPlugin

Interface for grid plugins.

interface GridPlugin {
  name: string;
  phase: number;
  dependencies?: string[];
  setup(store: GridStore, api: GridApiInterface, context: GridPluginSetupContext): PluginDisposable | void;
  dispose?(): void;
}

Properties:

• name: string - Unique plugin name
• phase: number - Initialization phase
• dependencies?: string[] - Names of required plugins
• setup(store, api, context) - Setup function called during initialization
• dispose?(): void - Cleanup function (optional)

GridPluginSetupContext

Live runtime option access for plugins.

interface GridPluginSetupContext {
  options: GridOptions;
  getOptions(): GridOptions;
  getOptionsSnapshot(): GridOptions;
  subscribeOptions(listener: GridOptionsListener): () => void;
}

const customPlugin: GridPlugin = {
  name: 'custom-plugin',
  phase: 60,
  setup(store, api, context) {
    const unsubscribeOptions = context.subscribeOptions((change) => {
      console.log('Updated option keys:', change.changedKeys);
    });

    return {
      teardown: [unsubscribeOptions]
    };
  },
  dispose() {
    // Cleanup
  }
};

grid.usePlugin(customPlugin);

Type Imports

import type {
  Grid,
  GridOptions,
  ColumnDef,
  CellRef,
  CellRange,
  SortState,
  FilterModel,
  FilterOperator,
  CellRenderer,
  RenderParams,
  CellEditor,
  EditorParams,
  HeaderRenderer,
  HeaderRenderParams,
  GridPlugin
} from '@zengrid/core';