Grid Props (React)

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 extends Row = Row> {
  columns: ColumnDefinition[];
  dataSource?: DataSource<TData>;
  rowData?: TData[];
  rowHeight: number;
  headerHeight?: number;
  overscan?: number;
  sortingEnabled?: boolean;
  darkMode?: boolean;
  wheelDampening?: number;
  /** Initial viewport width for SSR (pixels). ResizeObserver takes over on client. */
  initialWidth?: number;
  /** Initial viewport height for SSR (pixels). ResizeObserver takes over on client. */
  initialHeight?: number;
  cellRenderers?: Record<string, ReactCellRenderer>;
  editRenderers?: Record<string, ReactEditRenderer>;
  headerRenderers?: Record<string, ReactHeaderRenderer>;
  cellRenderer?: ReactCellRenderer;
  editRenderer?: ReactEditRenderer;
  headerRenderer?: ReactHeaderRenderer;
  rowDragEntireRow?: boolean;
  /** Function to extract unique ID from row. Required when onCellValueChanged is provided. */
  getRowId?: (row: TData) => RowId;
  /** Called when a cell value is changed via editing or fill drag. Requires getRowId. */
  onCellValueChanged?: (event: CellValueChangedEvent<TData>) => void;
  onRowDragEnd?: (sourceIndex: number, targetIndex: number) => void;
  onColumnMoved?: (fromIndex: number, toIndex: number) => void;
  onColumnResized?: (colIndex: number, newWidth: number) => void;
  /** Row/column/cell highlighting configuration. See Styling guide for usage. */
  highlighting?: HighlightingOptions<TData>;
  /** Custom loading component to render instead of default spinner. */
  loadingComponent?: React.ComponentType<{ isLoading: boolean }>;
  /** Optional ref to access GridCore API */
  gridRef?: React.MutableRefObject<GridRef<TData> | null>;
}

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.

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

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={(from, to) => dataSource.moveRow(from, to)}
/>

onRowDragEnd

Type: (sourceIndex: number, targetIndex: number) => 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={(sourceIndex, targetIndex) => {
    dataSource.moveRow(sourceIndex, targetIndex);
  }}
/>

onColumnMoved

Type: (fromIndex: number, toIndex: number) => void

Called when a column header is dragged to a new position. The consumer is responsible for reordering the columns array.

<Grid
  columns={columns}
  rowData={data}
  rowHeight={36}
  onColumnMoved={(fromIndex, toIndex) => {
    setColumns((prev) => {
      const next = [...prev];
      const [moved] = next.splice(fromIndex, 1);
      next.splice(toIndex, 0, moved);
      return next;
    });
  }}
/>

onColumnResized

Type: (colIndex: number, newWidth: number) => void

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

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

<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"] : [],
  }}
/>

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?.setSort("name", "asc");
gridRef.current?.core?.startEdit(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.

Grid Props