gp-grid-logo
API Reference

Grid Props

Reference for every prop accepted by the React Grid component, covering data sources, columns, selection, sorting, styling, and interactivity options.

The GridProps interface defines all properties accepted by the Grid component.

interface GridProps<TData = unknown> {
  columns: ColumnDefinition[];
  columnState?: ColumnStateUpdate[];
  columnLayout?: ColumnLayoutMode;
  dataSource?: DataSource<TData>;
  rowData?: TData[];
  rowHeight: number;
  headerHeight?: number;
  headerBandHeights?: readonly number[];
  columnGroups?: readonly ColumnGroupChild[];
  columnGroupLimits?: ColumnGroupLimits;
  onColumnSchemaRejected?: (error: ColumnSchemaError) => void;
  overscan?: number;
  columnOverscan?: number;
  rowLoading?: RowLoadingOptions;
  freezeRows?: FreezeRowsOptions;
  onFrozenRowsChanged?: (state: FrozenRowsState) => void;
  sortingEnabled?: boolean;
  darkMode?: boolean;
  wheelDampening?: number;
  maxFlingVelocity?: number;

  cellRenderers?: Record<string, ReactCellRenderer>;
  editRenderers?: Record<string, ReactEditRenderer>;
  headerRenderers?: ReactHeaderRendererRegistry;
  filterRenderers?: Record<string, ReactFilterRenderer>;

  cellRenderer?: ReactCellRenderer;
  editRenderer?: ReactEditRenderer;
  headerRenderer?: ReactHeaderRenderer;
  filterRenderer?: ReactFilterRenderer;
  pinIcon?: GridIcon;

  initialWidth?: number;
  initialHeight?: number;

  gridRef?: React.MutableRefObject<GridRef<TData> | null>;

  highlighting?: HighlightingOptions<TData>;

  getRowId?: (row: TData) => RowId;
  onCellValueChanged?: (event: CellValueChangedEvent<TData>) => void;
  onWriteRejected?: (event: CellWriteRejectedEvent) => void;
  onWriteCommitted?: (event: WriteCommittedEvent) => void;
  loadingComponent?: React.ComponentType<{ isLoading: boolean }>;
  rowDragEntireRow?: boolean;
  onRowDragEnd?: (event: RowDragEndEvent) => void;
  onColumnResized?: (event: ColumnResizedEvent) => void;
  rowResize?: boolean;
  onRowResized?: (event: RowResizedEvent) => void;
  autoFit?: AutoFitOptions;
  history?: HistoryOptions;
  onColumnMoved?: (event: ColumnMovedEvent) => void;
  onColumnPinned?: (event: ColumnPinnedEvent) => void;
  rowGrouping?: RowGrouping | null;
  groupLabelColumn?: string;
  groupLabelRenderer?: ReactGroupLabelRenderer;
  onRowGroupToggled?: (event: RowGroupToggledEvent) => void;
  onRowGroupingRejected?: (rejection: RowGroupingRejection) => void;
  labels?: GridLabelOverrides;
}

Required Props

columns

Type: ColumnDefinition[]

Array of column definitions. See Column Definition for details.

const columns: ColumnDefinition[] = [
  { field: "id", cellDataType: "number", width: 80 },
  { field: "name", cellDataType: "text", width: 200 },
];

rowHeight

Type: number

Height of each row in pixels.

<Grid columns={columns} rowData={data} rowHeight={36} />

Data Props

rowData

Type: TData[]

Array of row data objects. This is the simplest way to provide data.

const data = [
  { id: 1, name: "Giovanni" },
  { id: 2, name: "Luca" },
];

<Grid columns={columns} rowData={data} rowHeight={36} />

dataSource

Type: DataSource<TData>

Data source for advanced data handling. Use this for server-side data or when you need mutation capabilities. See Data Sources.

const dataSource = createClientDataSource(data);

<Grid columns={columns} dataSource={dataSource} rowHeight={36} />

Optional Props

headerHeight

Type: number Default: Same as rowHeight

Height of the header row in pixels.

<Grid columns={columns} rowData={data} rowHeight={36} headerHeight={48} />

overscan

Type: number Default: 3

Number of rows to render outside the visible viewport. Higher values improve scroll smoothness at the cost of more DOM elements.

<Grid columns={columns} rowData={data} rowHeight={36} overscan={5} />

sortingEnabled

Type: boolean Default: true

Enable or disable sorting globally.

<Grid columns={columns} rowData={data} rowHeight={36} sortingEnabled={false} />

darkMode

Type: boolean Default: false

Enable dark mode styling.

<Grid columns={columns} rowData={data} rowHeight={36} darkMode={true} />

wheelDampening

Type: number Default: 0.1

Dampening factor for wheel scrolling (0-1). Lower values = smoother but slower scrolling.

Enabling this prop activates smooth scrolling for grids that exceed millions of rows by using virtual dampening, which keeps wheel-based navigation fluid on very large datasets.

<Grid columns={columns} rowData={data} rowHeight={36} wheelDampening={0.2} />

maxFlingVelocity

Type: number Default: 20 × rowHeight

Maximum accumulated touch-fling velocity in logical px/ms when scroll virtualization is active. Pair higher values with overscan 10–12 for smoother fast scrolling on touch devices.

<Grid
  columns={columns}
  rowData={data}
  rowHeight={36}
  maxFlingVelocity={2000}
  overscan={12}
/>

Drag & Reorder Props

rowDragEntireRow

Type: boolean Default: false

When enabled, clicking and dragging any cell in a row initiates a row drag instead of cell selection.

<Grid
  columns={columns}
  dataSource={dataSource}
  rowHeight={36}
  rowDragEntireRow={true}
  onRowDragEnd={({ fromViewIndex, toViewIndex }) => dataSource.moveRow(fromViewIndex, toViewIndex)}
/>

onRowDragEnd

Type: ({ fromViewIndex, toViewIndex }: RowDragEndEvent) => void

Called when a row is dropped after dragging. The consumer is responsible for reordering the data.

<Grid
  columns={columns}
  dataSource={dataSource}
  rowHeight={36}
  onRowDragEnd={({ fromViewIndex, toViewIndex }) => {
    dataSource.moveRow(fromViewIndex, toViewIndex);
  }}
/>

onColumnMoved

Type: (event: ColumnMovedEvent) => void

Called when a column header is dragged to a new position. The core retains column order by identity; use this notification to persist state.

<Grid
  columns={columns}
  rowData={data}
  rowHeight={36}
  onColumnMoved={({ columnId, fromViewIndex, toViewIndex }) => {
    console.log(columnId, fromViewIndex, toViewIndex);
  }}
/>

onColumnResized

Type: (event: ColumnResizedEvent) => void

Called when a column is resized by dragging the header edge.

<Grid
  columns={columns}
  rowData={data}
  rowHeight={36}
  onColumnResized={({ columnId, width }) => {
    console.log(`Column ${columnId} resized to ${width}px`);
  }}
/>

SSR Props

initialWidth

Type: number

Initial viewport width in pixels for server-side rendering. On the client, a ResizeObserver takes over automatically.

initialHeight

Type: number

Initial viewport height in pixels for server-side rendering.

Identity & Edit Props

getRowId

Type: (row: TData) => RowId

Function to extract a unique ID from each row. Required when onCellValueChanged is provided.

<Grid
  columns={columns}
  rowData={data}
  rowHeight={36}
  getRowId={(row) => row.id}
  onCellValueChanged={(event) => console.log("Changed:", event)}
/>

onCellValueChanged

Type: (event: CellValueChangedEvent<TData>) => void

Called after a cell value is committed via inline editing or fill-handle drag. Requires getRowId to be set.

<Grid
  columns={columns}
  rowData={data}
  rowHeight={36}
  getRowId={(row) => row.id}
  onCellValueChanged={({ rowId, colIndex, oldValue, newValue }) => {
    console.log(`Row ${rowId} col ${colIndex}: ${oldValue} → ${newValue}`);
  }}
/>

Styling Props

highlighting

Type: HighlightingOptions<TData>

Dynamic row, column, and cell class computation. See the Styling guide for detailed usage.

<Grid
  columns={columns}
  rowData={data}
  rowHeight={36}
  highlighting={{
    computeRowClasses: (context) =>
      context.rowIndex != null && context.rowIndex % 2 === 1
        ? ["zebra-row"]
        : [],
    computeCellClasses: (context) =>
      context.isSelected ? ["bg-blue-50"] : [],
  }}
/>

Localization Props

labels

Type: GridLabelOverrides Default: English defaults

Override any user-visible grid string: the filter popup, its buttons and placeholders, the empty state and the error prefix. Unspecified labels keep their English defaults.

import { Grid, type GridLabelOverrides } from "@gp-grid/react";

const labels: GridLabelOverrides = {
  filterTitle: "Filtra: {column}", // {column} is the column header name
  and: "E",
  apply: "Applica",
  emptyState: "Nessun dato",
};

<Grid columns={columns} rowData={rows} rowHeight={36} labels={labels} />;

The most common keys:

KeyTokenMeaning
filterTitle{column}Filter popup title
and / or-Combination toggle
apply / clear / addCondition / removeCondition-Condition buttons
addGroup / removeGroup-Condition-group buttons
valuePlaceholder / searchPlaceholder / betweenSeparator-Inputs
valuesMode / conditionMode-Popup mode toggle
selectAll / deselectAll / blanks-Values-mode controls
tooManyValues{count}Too-many-values message
emptyState-Empty grid message
errorPrefix{message}Error message prefix
operators.*-Filter dropdown labels (contains, startsWith, between, …)

operators is also a partial override, so one operator can be changed without copying the English defaults:

import type { GridLabelOverrides } from "@gp-grid/react";

const labels: GridLabelOverrides = {
  operators: { contains: "Contiene" },
};

Loading Props

loadingComponent

Type: React.ComponentType<{ isLoading: boolean }>

Custom component rendered during data loading instead of the default spinner.

function MySpinner({ isLoading }: { isLoading: boolean }) {
  return isLoading ? <div className="animate-pulse">Loading…</div> : null;
}

<Grid
  columns={columns}
  dataSource={dataSource}
  rowHeight={36}
  loadingComponent={MySpinner}
/>

Ref Props

gridRef

Type: React.MutableRefObject<GridRef<TData> | null>

Ref handle exposing the underlying GridCore instance for imperative API access.

const gridRef = useRef<GridRef<MyRow>>(null);

// Later:
gridRef.current?.core?.sortFilter.setSort("name", "asc");
gridRef.current?.core?.edit.start(0, 1);

<Grid
  columns={columns}
  rowData={data}
  rowHeight={36}
  gridRef={gridRef}
/>

Renderer Props

cellRenderer

Type: ReactCellRenderer

Global cell renderer applied to all cells.

const MyCellRenderer = (params: CellRendererParams) => (
  <div>{params.value?.toString()}</div>
);

<Grid
  columns={columns}
  rowData={data}
  rowHeight={36}
  cellRenderer={MyCellRenderer}
/>

cellRenderers

Type: Record<string, ReactCellRenderer>

Registry of named cell renderers. Reference by key in column definitions.

<Grid
  columns={columns}
  rowData={data}
  rowHeight={36}
  cellRenderers={{
    status: StatusRenderer,
    currency: CurrencyRenderer,
  }}
/>

editRenderer / editRenderers

Type: ReactEditRenderer / Record<string, ReactEditRenderer>

Custom edit renderers for cells in edit mode.

headerRenderer / headerRenderers

Type: ReactHeaderRenderer / Record<string, ReactHeaderRenderer>

Custom header renderers.

filterRenderer / filterRenderers

Type: ReactFilterRenderer / Record<string, ReactFilterRenderer>

Custom filter popup content: filterRenderer applies to every filterable column, filterRenderers is the registry a column's filterRenderer key points into. See Custom Filter Popup.

Layout, grouping, and write options

The following options are shared across the bindings. Use React props, Vue kebab-case bindings, or Angular inputs; Angular callbacks are outputs.

OptionContract
columnStateColumnStateUpdate[]; controlled width, order, visibility, and pin overrides by columnId
columnLayout"fit" (default) or "fixed"
columnOverscanCenter-column overscan in CSS pixels; default 240
columnGroups / columnGroupLimitsNested column-id descriptors and creation-only validation budgets
headerBandHeightsConfigured height per header band
freezeRows{ count }; freezes leading displayed rows below the header
rowLoadingRow loading and cache configuration
rowResize / autoFitRow resize gestures and creation-only measurement bounds
rowGroupingOpaque grouping built by createRowGrouping, or null
groupLabelColumn / groupLabelRendererGroup and total label customization
historyCreation-only { maxEntries }; requires getRowId
pinIconCustom pin-toggle SVG
onColumnPinned / onRowResizedIdentity-bearing pin and row-size notifications
onFrozenRowsChangedEffective frozen count and limiting reason
onColumnSchemaRejected / onRowGroupingRejectedInvalid schema or unsupported grouping notifications
onRowGroupToggledUser-initiated group expansion notification
onWriteRejectedRejected write with reason and operation
onWriteCommittedOne event per write command, with changes and skips; requires getRowId

See the guides for contracts and examples, and the migration guide for API changes.

On this page