Quick Start

Get a working ZenGrid up and running with sorting, filtering, and selection in minutes.

Get a working ZenGrid up and running in minutes with sorting, filtering, and selection enabled.

Minimal Working Example

Create a container div and initialize the grid:

<div id="grid" style="width: 800px; height: 600px;"></div>

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

const container = document.getElementById('grid')!;

const grid = new Grid(container, {
  rowCount: 100,
  colCount: 5,
  rowHeight: 36,
  colWidth: 140,
});

grid.setData(
  Array.from({ length: 100 }, (_, row) =>
    Array.from({ length: 5 }, (_, col) => `Cell ${row},${col}`)
  )
);
grid.render();

ℹ Info

The grid requires explicit dimensions on the container element. The data callback is called on-demand for each visible cell.

Adding Columns

Define columns with headers, widths, and field mappings:

import { Grid, type ColumnDef } from '@zengrid/core';

const columns: ColumnDef[] = [
  { field: 'id', header: 'ID', width: 80 },
  { field: 'name', header: 'Name', width: 200 },
  { field: 'email', header: 'Email', width: 250 },
  { field: 'status', header: 'Status', width: 120 }
];

const dataset = [
  { id: 1, name: 'Alice', email: 'alice@example.com', status: 'Active' },
  { id: 2, name: 'Bob', email: 'bob@example.com', status: 'Inactive' }
];

const rows = dataset.map((record) => [
  record.id,
  record.name,
  record.email,
  record.status,
]);

const grid = new Grid(document.getElementById('grid')!, {
  columns,
  rowCount: rows.length,
  colCount: columns.length,
  rowHeight: 36,
  colWidth: columns.map((column) => column.width ?? 140),
});

grid.setData(rows);
grid.render();

Enable Sorting

Add sorting to any column programmatically:

// Sort a column ascending.
grid.sort.apply([{ column: 1, direction: 'asc' }]);

// Sort a column descending.
grid.sort.apply([{ column: 1, direction: 'desc' }]);

// Toggle sort direction.
grid.sort.toggle(1);

// Clear sorting.
grid.sort.clear();

💡 Tip

Enable sorting on specific columns by setting sortable: true in the column definition.

Enable Filtering

Add filtering to columns:

// Filter column by value
grid.filter.set(1, 'contains', 'Alice');

// Filter with different operators
grid.filter.set(2, 'startsWith', 'admin');
grid.filter.set(0, 'equals', 123);

// Clear filters
grid.filter.clear();

Enable Selection

Enable selection in grid options:

const grid = new Grid(document.getElementById('grid')!, {
  rowCount: 100,
  colCount: 5,
  rowHeight: 36,
  colWidth: 140,
  enableSelection: true,
  enableMultiSelection: true,
  selectionType: 'range' // 'cell', 'row', 'column', or 'range'
});

// Listen to selection changes
grid.on('selection:change', (payload) => {
  console.log('Selected ranges:', payload.ranges);
});

ℹ Info

Selection types are cell, row, column, and range. Use enableMultiSelection when users should be able to keep multiple ranges selected.

Full Working Example

Here’s a complete example combining all features:

import { Grid, type ColumnDef } from '@zengrid/core';

const columns: ColumnDef[] = [
  { field: 'id', header: 'ID', width: 80, sortable: true },
  { field: 'name', header: 'Name', width: 200, sortable: true, filterable: true },
  { field: 'email', header: 'Email', width: 250, filterable: true },
  { field: 'status', header: 'Status', width: 120 }
];

const dataset = [
  { id: 1, name: 'Alice', email: 'alice@example.com', status: 'Active' },
  { id: 2, name: 'Bob', email: 'bob@example.com', status: 'Inactive' },
  { id: 3, name: 'Charlie', email: 'charlie@example.com', status: 'Active' }
];

const rows = dataset.map((record) => [
  record.id,
  record.name,
  record.email,
  record.status,
]);

const grid = new Grid(document.getElementById('grid')!, {
  columns,
  rowCount: rows.length,
  colCount: columns.length,
  rowHeight: 36,
  colWidth: columns.map((column) => column.width ?? 140),
  enableSelection: true,
  enableMultiSelection: true,
  selectionType: 'range'
});

grid.setData(rows);
grid.render();

// Handle events
grid.on('cell:click', ({ cell, value }) => {
  console.log(`Clicked cell at row ${cell.row}, col ${cell.col}: ${value}`);
});

Next Steps

Continue to Your First Grid for a detailed step-by-step tutorial building a full-featured data grid.