Basic Usage

HTML/CSS Prerequisites

Currently the Grid depends on there being a root level "portal" div in your HTML. Insert this snippet as the last child of your <body> tag:

<div id="portal" style="position: fixed; left: 0; top: 0; z-index: 9999;" />

Once you've got that done, the easiest way to use the Data Grid is to give it a fixed size:

<DataEditor width={500} height={300} {...props} />

Changes to your data

The Grid will never change any of your underlying data. You have to do so yourself when one of the callbacks is invoked. For example, when the user edits the value in a cell, the Grid will invoke the onCellEdited callback. If you don't implement that callback, or if it doesn't change the undelying data to the new value, the Grid will keep displaying the old value.


interface DataEditorProps {
    allowedFillDirections?: "horizontal" | "vertical" | "orthogonal" | "any",
    className?: string;
    coercePasteValue?: ((val, cell) => undefined | GridCell);
    columnSelect?: "none" | "single" | "multi";
    columnSelectionBlending?: SelectionBlending;
    columns: readonly GridColumn[];
    copyHeaders?: boolean;
    customRenderers?: readonly CustomRenderer<any>[];
    drawCell?: DrawCellCallback;
    drawFocusRing?: boolean;
    drawHeader?: DrawHeaderCallback;
    experimental?: {
        disableAccessibilityTree?: boolean;
        disableMinimumCellWidth?: boolean;
        enableFirefoxRescaling?: boolean;
        hyperWrapping?: boolean;
        isSubGrid?: boolean;
        kineticScrollPerfHack?: boolean;
        paddingBottom?: number;
        paddingRight?: number;
        renderStrategy?: "single-buffer" | "double-buffer" | "direct";
        scrollbarWidthOverride?: number;
        strict?: boolean;
    fillHandle?: boolean;
    fixedShadowX?: boolean;
    fixedShadowY?: boolean;
    freezeColumns?: number;
    freezeTrailingRows?: number;
    getCellContent: ((cell) => GridCell);
    getCellsForSelection?: true | ((selection, abortSignal) => GetCellsThunk | CellArray);
    getGroupDetails?: GroupDetailsCallback;
    getRowThemeOverride?: GetRowThemeCallback;
    gridSelection?: GridSelection;
    groupHeaderHeight?: number;
    headerHeight?: number;
    headerIcons?: SpriteMap;
    height?: string | number;
    highlightRegions?: readonly Highlight[];
    imageEditorOverride?: ImageEditorType;
    imageWindowLoader?: ImageWindowLoader;
    initialSize?: readonly [number, number];
    isDraggable?: boolean | "header" | "cell";
    isOutsideClick?: ((e) => boolean);
    keybindings?: Partial<Keybinds>;
    markdownDivCreateNode?: ((content) => DocumentFragment);
    maxColumnAutoWidth?: number;
    maxColumnWidth?: number;
    minColumnWidth?: number;
    onCellActivated?: ((cell) => void);
    onCellClicked?: ((cell, event) => void);
    onCellContextMenu?: ((cell, event) => void);
    onCellEdited?: ((cell, newValue) => void);
    onCellsEdited?: ((newValues) => boolean | void);
    onColumnMoved?: ((startIndex, endIndex) => void);
    onColumnResize?: ((column, newSize, colIndex, newSizeWithGrow) => void);
    onColumnResizeEnd?: ((column, newSize, colIndex, newSizeWithGrow) => void);
    onColumnResizeStart?: ((column, newSize, colIndex, newSizeWithGrow) => void);
    onDelete?: ((selection) => boolean | GridSelection);
    onDragLeave?: (() => void);
    onDragOverCell?: ((cell, dataTransfer) => void);
    onDragStart?: ((args) => void);
    onDrop?: ((cell, dataTransfer) => void);
    onFillPattern?: ((event) => void);
    onFinishedEditing?: ((newValue, movement) => void);
    onGridSelectionChange?: ((newSelection) => void);
    onGroupHeaderClicked?: ((colIndex, event) => void);
    onGroupHeaderContextMenu?: ((colIndex, event) => void);
    onGroupHeaderRenamed?: ((groupName, newVal) => void);
    onHeaderClicked?: ((colIndex, event) => void);
    onHeaderContextMenu?: ((colIndex, event) => void);
    onHeaderMenuClick?: ((col, screenPosition) => void);
    onItemHovered?: ((args) => void);
    onKeyDown?: ((event) => void);
    onKeyUp?: ((event) => void);
    onMouseMove?: ((args) => void);
    onPaste?: boolean | ((target, values) => boolean);
    onRowAppended?: (() => void | Promise<undefined | number | "bottom" | "top">);
    onRowMoved?: ((startIndex, endIndex) => void);
    onSearchClose?: (() => void);
    onSearchResultsChanged?: ((results, navIndex) => void);
    onSearchValueChange?: ((newVal) => void);
    onSelectionCleared?: (() => void);
    onVisibleRegionChanged?: ((range, tx, ty, extras) => void);
    overscrollX?: number;
    overscrollY?: number;
    preventDiagonalScrolling?: boolean;
    provideEditor?: ProvideEditorCallback<GridCell>;
    rangeSelect?: "rect" | "none" | "cell" | "multi-cell" | "multi-rect";
    rangeSelectionBlending?: SelectionBlending;
    rightElement?: ReactNode;
    rightElementProps?: {
        fill?: boolean;
        sticky?: boolean;
    rowHeight?: number | ((index) => number);
    rowMarkerStartIndex?: number;
    rowMarkerTheme?: Partial<Theme>;
    rowMarkerWidth?: number;
    rowMarkers?: "number" | "none" | "checkbox" | "both" | "checkbox-visible" | "clickable-number";
    rowSelect?: "none" | "single" | "multi";
    rowSelectionBlending?: SelectionBlending;
    rowSelectionMode?: "auto" | "multi";
    rows: number;
    scaleToRem?: boolean;
    scrollOffsetX?: number;
    scrollOffsetY?: number;
    searchResults?: readonly Item[];
    searchValue?: string;
    showSearch?: boolean;
    smoothScrollX?: boolean;
    smoothScrollY?: boolean;
    spanRangeBehavior?: "default" | "allowPartial";
    theme?: Partial<Theme>;
    trailingRowOptions?: {
        addIcon?: string;
        hint?: string;
        sticky?: boolean;
        targetColumn?: number | GridColumn;
        tint?: boolean;
    validateCell?: ((cell, newValue, prevValue) => boolean | ValidatedGridCell);
    verticalBorder?: boolean | ((col) => boolean);
    width?: string | number;

Required Props

All data grids must set these props. These props are the bare minimum required to set up a functional data grid. Not all features will function with only these props but basic functionality will be present.


All columns in the data grid.

A callback to get the content of a given cell location.

The number of rows in the data-grid.

Important Props

Most data grids will want to set the majority of these props one way or another.


Enable/disable a shadow behind fixed columns on the X axis.

Enable/disable a shadow behind the header(s) on the Y axis.

The number of columns which should remain in place when scrolling horizontally. The row marker column, if enabled is always frozen and is not included in this count.

The number of rows which should remain in place at the bottom of the grid when scrolling.

Used to fetch large amounts of cells at once. Used for copy/paste, if unset copy will not work.


Overrides the height of the grid.

If specified, it will be used to render Markdown, instead of the default Markdown renderer used by the Grid. You'll want to use this if you need to process your Markdown for security purposes, or if you want to use a renderer with different Markdown features.

Emits whenever the visible rows/columns changes.

Callback for providing a custom editor for a cell.

Callback or number used to specify the height of a given row.

Enable/disable smooth scrolling on the X axis.

Enable/disable smooth scrolling on the Y axis.


Overrides the width of the grid.


Emitted when the search interface close button is clicked.

Emitted when the search results change.

Emitted when the user types a new value into the search box.

Overrides the search results and highlights all items for the user to enumerate over.

Sets the search value for the search box.

Show/hide the search interface.

Row Markers


Enable/disable row marker column on the left. Can show row numbers, selection boxes, or both.

The index of the first element in the grid

Overrides the theme for row markers

The width of the row markers.



Callback to provide additional details for group headers such as icons.

Callback to provide theme override for any row.

The height in pixels of the column group headers.

The height in pixels of the column headers.

Additional header icons for use by GridColumn.

Allows overscrolling the data grid horizontally by a set amount.

Allows overscrolling the data grid vertically by a set amount.

A node which will be placed at the right edge of the data grid.

Changes how the right element renders.

Scales most elements in the theme to match rem scaling automatically

Enable/disable vertical borders for any GridColumn

Selection Handling



Controls which directions fill is allowed in while using the fill handle.

Controls if multiple columns can be selected at once.

Controls how column selections may be mixed with other selection types.

Determins if the focus ring should be drawn by the grid.

Controls the presence of the fill indicator

The current selection active in the data grid. Includes both the selection cell and the selected range.

Adds additional highlights to the data grid for showing contextually important cells.

Emitted whenever the gridSelection should change.

Emitted when the selection is explicitly cleared.

Controls if multiple ranges can be selected at once.

Controls how range selections may be mixed with other selection types.

Controls if multiple rows can be selected at aonce.

Controls how row selections may be mixed with other selection types.

Determines if the gridSelection should allow partial spans or not.



Allows coercion of pasted values.

Used to provide an override to the default image editor for the data grid. provideEditor may be a better choice for most people.

Emitted whenever a cell edit is completed.

Emitted whenever a cell edit is completed and provides all edits inbound as a single batch.

Emitted whenever the user has requested the deletion of the selection.

Emitted when the fill handle is used to replace the contents of a region of the grid.

Emitted when editing has finished, regardless of data changing or not.

Emitted whe the user wishes to rename a group.

Emitted any time data is pasted to the grid. Allows controlling paste behavior.

Emitted whenever a row append operation is requested. Append location can be set in callback.

Controls the built in trailing row to allow appending new rows.


Setting to true will cause the grid to prevent focus leaving the grid during caret browsing or pressing tab.

When returns false indicates to the user the value will not be accepted. When returns a new GridCell the value is coerced to match.

Input Interaction


Controls which keybindings are enabled while the grid is selected.

Sets the maximum width a column can be auto-sized to.

Sets the maximum width the user can resize a column to.

Sets the minimum width the user can resize a column to.

Emitted when a cell is activated, by pressing Enter, Space or double clicking it.

Emitted when a cell is clicked.

Emitted when a cell should show a context menu. Usually right click.

Emitted when a column has been dragged to a new location.


Called when the user is dragging a column and proposes to move it to a new location. Return false to prevent

Emitted when a column has been resized to a new size.

Emitted when a column has been resized to a new size and the user has stopped interacting wtih the resize handle.

Emitted when a column resize operation begins.

Emitted when a group header is clicked.

Emitted when a group header should show a context menu. Usually right click.

Emitted when a column header is clicked.

Emitted when a column header should show a context menu. Usually right click.

Emitted when the menu dropdown arrow on a column header is clicked.

Emitted when the hovered item changes.


Emitted when a key is pressed.


Emitted when a key is released.

Emitted whenever the mouse moves. Be careful, can cause performance issues.

Emitted when a row has been dragged to a new location.

Prevents diagonal scrolling

Determines if row selection requires a modifier key to enable multi-selection or not.

Drag and Drop


Emitted when an external drag event exits the drop region.

Emitted when an external drag event is started over a cell.

Emitted when an external drag event is completed on the grid.

Custom Cells



Callback used to override the rendering of any cell.

Callback used to override the rendering of any header.

Rarely Used



Contains experimental flags. Nothing in here is considered stable API and is mostly used for features that are not yet settled.


Replaces the default image window loader with an externally provided one. Useful for cases where images need to be loaded in a non-standard method.


Passing this enables the grid to optimize its first paint and avoid a flicker. Only useful if the grid size is known ahead of time.


Makes the grid as a whole draggable. Disables many interactions.


Allows bypassing the default outside click handler for overlay editors.


Emitted when a drag starts and isDraggable is true.


Sets the initial scroll offset in the x direction.


Sets the initial scroll offset in the y direction.

Last updated