API reference.

Quick start

Give the host a width and height, then construct the grid after the element mounts. The core uses browser DOM APIs and has no runtime framework dependency.

import { RapidGrid, DataType } from 'rapid-grid';
import 'rapid-grid/style.css';

const grid = new RapidGrid('#grid', {
  items: [{ name: 'Northstar', revenue: 12400 }],
  columns: [
    { binding: 'name', header: 'Account', width: 180 },
    { binding: 'revenue', header: 'Revenue', dataType: DataType.Number, format: 'c0' }
  ]
});

// On component cleanup:
grid.destroy();

GridOptions

Pass this object as the optional second argument to new RapidGrid(host, options). Columns default to the keys of the first item when omitted.

ColumnOptions

Each column binds to a key in a data item. Custom editors are DOM factories and should return an input, select, textarea, or a container holding one.

const statusEditor = value => {
  const select = document.createElement('select');
  for (const label of ['New', 'Review', 'Done']) select.add(new Option(label, label));
  select.value = String(value ?? '');
  return select;
};

{ binding: 'status', header: 'Status', editor: statusEditor }

RapidGrid

Constructor and properties

Lookup and layout

Editing, selection, and clipboard

Pointer drag, Shift-click, and Shift+Arrow extend a cell range. Ctrl/Cmd+C and Ctrl/Cmd+V use the browser clipboard when the grid has focus. Read-only columns are skipped during paste. The clipboard operations limit a request to one million cells.

Events

Each on… registration accepts (grid, args) and returns an unsubscribe function. A changing event can be cancelled by returning false or setting args.cancel = true.

Event argument shapes

FormatItemEventArgs = { panel, row, col, cellElement, dataItem }
CellEditEventArgs = { row, col, dataItem, oldValue, value, cellElement, cancel }
CellRangeEventArgs = { oldRanges, ranges, cancel }
DragEventArgs = { from, to }

Collections

CollectionView

Owns the mutable item array. items is a read-only view of its reference; mutations through the methods notify the grid.

Row and RowCollection

new RowCollection(count, defaultHeight, onLayout) builds the indexed row state; new Row(index, collection) is also exported. grid.rows exposes length, defaultHeight, sizes: PrefixSum, get(index), setHeight(index, px), reset(count), and move(from, to). A Row exposes index, mutable height, header, and allowMerging. Change the header or merging flag, then call grid.refresh().

Column and ColumnCollection

new ColumnCollection(options, defaultWidth, onLayout) builds the indexed column state; new Column(options, index, collection) is also exported. grid.columns exposes length, defaultWidth, sizes: PrefixSum, get(indexOrBinding), toArray(), setWidth(index, px), and move(from, to). A Column exposes index, mutable width, binding, header, dataType, format, allowMerging, readOnly, and editor. Refresh after changing formatting or merge flags.

Ranges & panels

CellRange

new CellRange(row, col, row2?, col2?) normalizes both corners. It exposes row, col, row2, col2, isValid, contains(row, col), and intersects(otherRange).

GridPanel

new GridPanel(kind, hostElement) stores the panel kind and DOM host. The kind is one of cells, columnHeaders, rowHeaders, or topLeftCells.

HitTestInfo

hitTest returns { panel, row, col, nearRightEdge, nearBottomEdge }. Row or column is -1 when that coordinate does not belong to the panel.

MergeManager

new MergeManager(view, rows, cols, format, mode) accepts a CollectionView, RowCollection, ColumnCollection, (row, col) => string formatter, and () => AllowMerging mode callback. It exposes getCellRange(row, col), getHeaderRange(kind, index), and clear(). Most applications use grid.getCell() instead.

Enums & data types

Formatting and parsing

formatValue(value, column, locale?) produces display text. parseValue(text, column, locale?) parses edited and pasted values; invalid typed values throw. Empty input becomes null for most typed columns, false for Boolean, and an empty string for String.

Virtualization building blocks

These classes are exported for advanced integrations. The grid constructs and manages them automatically for ordinary use.

PrefixSum

new PrefixSum(count, size) tracks row heights or column widths. Members: count, total, get(index), set(index, size), resize(count, defaultSize), move(from, to), offset(index), range(start, end), and indexAt(pixel). Offset lookup is indexed, and pixel-to-index lookup uses binary search. Size changes rebuild affected offsets lazily.

VirtualScroller

new VirtualScroller(viewport, rowSizes, colSizes, overscanRows, overscanCols, threshold, render) observes passive scroll events and calls render(window) on animation frames. Members: schedule(), refresh(), destroy(), and isFast. VirtualWindow gives inclusive row and column bounds plus a fast-scroll flag.

DOMPool

new DOMPool(container, className, onRelease?) reuses elements for keyed cells. Members: reconcile(keys, bind), get(key), forEachActive(callback), and clear(). The optional release callback runs before an active element is reused or removed.

Clipboard helpers

serializeTsv(rows) converts a matrix of strings to tab-separated text, quoting cells that contain tabs, line breaks, or quotes. parseTsv(text) reads that text back into a string matrix. Grid clipboard operations use these helpers internally.

import { serializeTsv, parseTsv } from 'rapid-grid';

const text = serializeTsv([['North', '12'], ['South', '24']]);
const rows = parseTsv(text); // [['North', '12'], ['South', '24']]