Row Nodes

Every row in a GridStorm grid is represented by a RowNode<TData> object. Row nodes wrap your data objects with metadata needed for rendering, selection, grouping, aggregation, and virtual scrolling.

interface RowNode<TData = any> {
  id: string;
  data: TData | undefined;
  sourceIndex: number;
  displayIndex: number;
  level: number;
  rowHeight: number;
  rowTop: number;
  parent: RowNode<TData> | null;
  children: RowNode<TData>[] | null;
  expanded: boolean;
  group: boolean;
  groupField: string | null;
  groupValue: any;
  leafChildrenCount: number;
  aggData: Record<string, any> | null;
  selected: boolean;
  selectable: boolean;
  detail: boolean;
  rowPinned: 'top' | 'bottom' | null;
  version: number;
}

Identity Fields

Nesting

Display Geometry

Tree and Group Fields

Aggregation Fields

// For a group row with aggFunc: 'sum' on salary, aggFunc: 'avg' on age:
node.aggData // { salary: 450000, age: 32.5 }

Selection Fields

Detail Fields

Pinning Fields

Version Tracking

Row Types

Data Rows

Standard rows that hold your data objects:

node.group === false
node.data !== undefined
node.children === null
node.rowPinned === null

Group Rows

Created by the grouping plugin when ColumnDef.rowGroup is enabled:

node.group === true
node.data === undefined
node.children !== null      // array of child RowNodes
node.groupField === 'department'
node.groupValue === 'Engineering'
node.leafChildrenCount === 15
node.expanded === true      // or false

Pinned Rows

Created from pinnedTopRowData or pinnedBottomRowData. Excluded from sorting, filtering, and pagination:

node.rowPinned === 'top'    // or 'bottom'
node.data !== undefined     // holds the pinned row data

Detail Rows

Used in master-detail layouts for expandable sub-content:

node.detail === true

Accessing Row Nodes

By ID

const node = api.getRowNode('emp-123');
if (node) {
  console.log(node.data?.name, node.selected);
}

By Display Index

const firstRow = api.getDisplayedRowAtIndex(0);
const lastRow = api.getDisplayedRowAtIndex(api.getDisplayedRowCount() - 1);

Iterating All Nodes

api.forEachNode((node, index) => {
  if (node.selected) {
    console.log('Selected:', node.id, node.data?.name);
  }
});

From Selected Rows

const selectedNodes = api.getSelectedNodes();
const selectedData = api.getSelectedRows(); // returns TData[]

From Grid State

const state = api.getState();
const totalNodes = state.rowNodes.size;           // Map<string, RowNode>
const displayedCount = state.displayedRowIds.length; // string[]

// Look up a specific node from state
const node = state.rowNodes.get('emp-123');

Row Node Events

Many grid events include the affected row node in their payload. Subscribe via api.addEventListener.

api.addEventListener('cell:clicked', (event) => {
  console.log('Clicked row:', event.node.id, 'column:', event.colId);
});

api.addEventListener('row:groupOpened', (event) => {
  console.log('Group', event.node.groupValue, 'expanded:', event.expanded);
});

api.addEventListener('cell:valueChanged', (event) => {
  console.log('Row', event.node.id, 'changed:', event.oldValue, '->', event.newValue);
});

Row Node Lifecycle

Row nodes go through several stages during their lifetime in the grid:

1. Creation

Row nodes are created when data is provided to the grid via GridConfig.rowData, api.setRowData(), or api.addRows(). The grid engine calls createRowNodes() which:

• Assigns each node a unique id (from getRowId or array index)
• Sets sourceIndex to the position in the input array
• Sets rowHeight from GridConfig.rowHeight
• Initializes version to 0

2. Processing

After creation, the row processing pipeline runs:

1. Filtering -- Nodes not matching the filter model or quick filter are excluded from display.
2. Sorting -- Remaining nodes are sorted according to the sort model.
3. Grouping -- If grouping is active, group nodes are created and data nodes are nested under them.
4. Display assignment -- Each visible node receives a displayIndex and rowTop value.

3. Mutation

Row nodes use a mutable internal design for performance. Properties that change at runtime:

4. Update

To update a cell value, use the transaction API or direct mutation:

api.updateRows([
  { id: 'emp-123', data: { salary: 95000 } },
]);

const node = api.getRowNode('emp-123');
if (node?.data) {
  node.data.salary = 95000;
  node.version++;
  api.refreshCells({ rowIds: ['emp-123'], colIds: ['salary'] });
}

:::caution Direct mutation bypasses the command bus and event system. For tracked, auditable changes, use api.updateRows() or the editing system instead. :::

5. Removal

Nodes are removed via api.removeRows() or replaced entirely via api.setRowData(). Removed nodes are deleted from GridState.rowNodes and from the selection set.

api.removeRows(['emp-123', 'emp-456']);

GridState Row Collections

The grid state contains two row-related collections:

const state = api.getState();

// All nodes
for (const [id, node] of state.rowNodes) {
  console.log(id, node.group ? 'group' : 'data');
}

// Displayed nodes in order
for (const id of state.displayedRowIds) {
  const node = state.rowNodes.get(id);
  console.log(node?.displayIndex, node?.data);
}

Related Types

GetRowIdParams

interface GetRowIdParams<TData> {
  data: TData;           // The row data object
  index: number;         // Zero-based index in the input data array
  parentKeys?: string[]; // Parent group keys for grouped/tree data
}

RowModelType

type RowModelType = 'client' | 'server' | 'infinite' | 'viewport';

SelectionSource

type SelectionSource = 'api' | 'checkbox' | 'click' | 'keyboard' | 'selectAll';