GridConfig

The GridConfig<TData> interface defines every option for creating a GridStorm grid instance. Pass it to createGrid() in vanilla TypeScript or as props to the <GridStorm> React component.

interface GridConfig<TData = any> {
  columns: ColumnDef<TData>[];
  rowData?: TData[];
  dataSource?: DataSource<TData>;
  rowModelType?: RowModelType;
  getRowId?: (params: GetRowIdParams<TData>) => string;
  plugins?: GridPlugin<TData>[];
  defaultColDef?: Partial<ColumnDef<TData>>;
  rowHeight?: number | ((params: { data: TData; index: number }) => number);
  headerHeight?: number;
  domLayout?: 'normal' | 'autoHeight' | 'print';
  pinnedTopRowData?: TData[];
  pinnedBottomRowData?: TData[];
  suppressScrollX?: boolean;
  suppressScrollY?: boolean;
  rowSelection?: RowSelectionMode;
  editType?: EditType;
  undoRedoCellEditing?: boolean;
  pagination?: boolean;
  paginationPageSize?: number;
  animateRows?: boolean;
  ariaLabel?: string;
  locale?: string;
  theme?: string;
  onGridReady?: (api: GridApi<TData>) => void;
  onRowDataChanged?: (event: GridEventMap<TData>['rowData:changed']) => void;
  onSelectionChanged?: (event: GridEventMap<TData>['selection:changed']) => void;
  onSortChanged?: (event: GridEventMap<TData>['column:sort:changed']) => void;
  onFilterChanged?: (event: GridEventMap<TData>['filter:changed']) => void;
  onCellValueChanged?: (event: GridEventMap<TData>['cell:valueChanged']) => void;
}

Data Options

import { createGrid } from '@gridstorm/core';

const engine = createGrid({
  columns: [{ field: 'name' }, { field: 'email' }],
  rowData: [
    { id: 1, name: 'Alice', email: 'alice@example.com' },
    { id: 2, name: 'Bob', email: 'bob@example.com' },
  ],
  rowModelType: 'client',
  getRowId: (params) => String(params.data.id),
});

Column Options

const engine = createGrid({
  columns: [
    { field: 'name', headerName: 'Full Name' },
    { field: 'salary', width: 120 },
  ],
  rowData: employees,
  defaultColDef: {
    sortable: true,
    resizable: true,
    width: 150,
    filterable: true,
  },
});

Layout Options

const engine = createGrid({
  columns,
  rowData,
  rowHeight: 48,
  headerHeight: 56,
  domLayout: 'normal',
});

// Variable row heights
const engine2 = createGrid({
  columns,
  rowData,
  rowHeight: ({ data }) => data.hasDetails ? 80 : 40,
});

Pinned Rows

const engine = createGrid({
  columns,
  rowData,
  pinnedTopRowData: [{ name: 'Header Row', salary: null }],
  pinnedBottomRowData: [{ name: 'Total', salary: 1250000 }],
});

Scrolling Options

Pagination Options

const engine = createGrid({
  columns,
  rowData,
  pagination: true,
  paginationPageSize: 25,
});

Selection Options

const engine = createGrid({
  columns,
  rowData,
  rowSelection: 'multiple',
});

Editing Options

const engine = createGrid({
  columns: [
    { field: 'name', editable: true },
    { field: 'salary', editable: true, cellEditor: 'number' },
  ],
  rowData,
  editType: 'cell',
  undoRedoCellEditing: true,
});

Styling Options

const engine = createGrid({
  columns,
  rowData,
  theme: 'gridstorm-dark',
  animateRows: true,
});

Accessibility and Locale

const engine = createGrid({
  columns,
  rowData,
  ariaLabel: 'Employee data table',
  locale: 'de-DE',
});

Callback Options

const engine = createGrid({
  columns,
  rowData,
  onGridReady: (api) => {
    api.setFilterModel({ status: { filterType: 'text', filter: 'active' } });
  },
  onSelectionChanged: (event) => {
    console.log('Selected:', event.selectedNodes.length, 'rows');
  },
  onSortChanged: (event) => {
    console.log('Sort model:', event.sortModel);
  },
  onFilterChanged: (event) => {
    console.log('Filters:', Object.keys(event.filterModel));
  },
  onCellValueChanged: (event) => {
    console.log(`Cell ${event.colId} changed from`, event.oldValue, 'to', event.newValue);
  },
});

Plugins

import { sortingPlugin } from '@gridstorm/plugin-sorting';
import { filterPlugin } from '@gridstorm/plugin-filtering';
import { selectionPlugin } from '@gridstorm/plugin-selection';
import { editingPlugin } from '@gridstorm/plugin-editing';

const engine = createGrid({
  columns,
  rowData,
  plugins: [
    sortingPlugin(),
    filterPlugin(),
    selectionPlugin(),
    editingPlugin(),
  ],
});

Supporting 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
}

DataSource

interface DataSource<TData> {
  getRows(params: DataSourceRequest): Promise<DataSourceResult<TData>>;
  destroy?(): void;
}

DataSourceRequest

interface DataSourceRequest {
  startRow: number;                          // First row index (inclusive, zero-based)
  endRow: number;                            // Last row index (exclusive)
  sortModel: SortModelItem[];                // Current sort model
  filterModel: Record<string, FilterModel>;  // Current filter model
  groupKeys: string[];                       // Expanded group path
  pivotCols: string[];                       // Pivot column IDs
  pivotMode: boolean;                        // Whether pivot mode is active
  valueCols: string[];                       // Value columns for aggregation
  rowGroupCols: string[];                    // Row grouping columns
}

DataSourceResult

interface DataSourceResult<TData> {
  rowData: TData[];   // Row data for the requested range
  rowCount: number;   // Number of rows returned
  lastRow?: number;   // Total dataset size (omit for infinite scrolling)
}

Full Example

import { createGrid } from '@gridstorm/core';
import { sortingPlugin } from '@gridstorm/plugin-sorting';
import { selectionPlugin } from '@gridstorm/plugin-selection';
import { paginationPlugin } from '@gridstorm/plugin-pagination';

interface Employee {
  id: number;
  name: string;
  department: string;
  salary: number;
}

const engine = createGrid<Employee>({
  columns: [
    { field: 'name', headerName: 'Full Name', sortable: true, flex: 1 },
    { field: 'department', sortable: true, width: 150 },
    { field: 'salary', sortable: true, width: 120,
      valueFormatter: ({ value }) => `$${value.toLocaleString()}` },
  ],
  rowData: employees,
  getRowId: (params) => String(params.data.id),
  plugins: [sortingPlugin(), selectionPlugin(), paginationPlugin()],
  defaultColDef: { resizable: true, filterable: true },
  rowHeight: 44,
  headerHeight: 48,
  rowSelection: 'multiple',
  pagination: true,
  paginationPageSize: 50,
  animateRows: true,
  ariaLabel: 'Employee directory',
  locale: 'en-US',
  theme: 'gridstorm-light',
  onGridReady: (api) => {
    api.setSortModel([{ colId: 'name', sort: 'asc' }]);
  },
  onSelectionChanged: ({ selectedNodes }) => {
    console.log(selectedNodes.length, 'rows selected');
  },
});