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:
| Key | Token | Meaning |
|---|---|---|
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.
| Option | Contract |
|---|---|
columnState | ColumnStateUpdate[]; controlled width, order, visibility, and pin overrides by columnId |
columnLayout | "fit" (default) or "fixed" |
columnOverscan | Center-column overscan in CSS pixels; default 240 |
columnGroups / columnGroupLimits | Nested column-id descriptors and creation-only validation budgets |
headerBandHeights | Configured height per header band |
freezeRows | { count }; freezes leading displayed rows below the header |
rowLoading | Row loading and cache configuration |
rowResize / autoFit | Row resize gestures and creation-only measurement bounds |
rowGrouping | Opaque grouping built by createRowGrouping, or null |
groupLabelColumn / groupLabelRenderer | Group and total label customization |
history | Creation-only { maxEntries }; requires getRowId |
pinIcon | Custom pin-toggle SVG |
onColumnPinned / onRowResized | Identity-bearing pin and row-size notifications |
onFrozenRowsChanged | Effective frozen count and limiting reason |
onColumnSchemaRejected / onRowGroupingRejected | Invalid schema or unsupported grouping notifications |
onRowGroupToggled | User-initiated group expansion notification |
onWriteRejected | Rejected write with reason and operation |
onWriteCommitted | One event per write command, with changes and skips; requires getRowId |
See the guides for contracts and examples, and the migration guide for API changes.
API Overview
Browse the full API reference for @gp-grid/react with details on every component, prop, event, and helper exported by the React integration package today.
Column Definition
Configure each React grid column individually with type, width, sorting, filtering, rendering, and editing options through the column definition object.