DataEditor

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.

Definition

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.

Name
Description

columns

All columns in the data grid.

getCellContent

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

rows

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.

Name
Description

fixedShadowX

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

fixedShadowY

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

freezeColumns

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.

freezeTrailingRows

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

getCellsForSelection

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

height

Overrides the height of the grid.

markdownDivCreateNode

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.

onVisibleRegionChanged

Emits whenever the visible rows/columns changes.

provideEditor

Callback for providing a custom editor for a cell.

rowHeight

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

smoothScrollX

Enable/disable smooth scrolling on the X axis.

smoothScrollY

Enable/disable smooth scrolling on the Y axis.

width

Overrides the width of the grid.

Search

Name
Description

onSearchClose

Emitted when the search interface close button is clicked.

onSearchResultsChanged

Emitted when the search results change.

onSearchValueChange

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

searchResults

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

searchValue

Sets the search value for the search box.

showSearch

Show/hide the search interface.

Row Markers

Name
Description

rowMarkers

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

rowMarkerStartIndex

The index of the first element in the grid

rowMarkerTheme

Overrides the theme for row markers

rowMarkerWidth

The width of the row markers.

Styling

Name
Description

getGroupDetails

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

getRowThemeOverride

Callback to provide theme override for any row.

groupHeaderHeight

The height in pixels of the column group headers.

headerHeight

The height in pixels of the column headers.

headerIcons

Additional header icons for use by GridColumn.

overscrollX

Allows overscrolling the data grid horizontally by a set amount.

overscrollY

Allows overscrolling the data grid vertically by a set amount.

rightElement

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

rightElementProps

Changes how the right element renders.

scaleToRem

Scales most elements in the theme to match rem scaling automatically

verticalBorder

Enable/disable vertical borders for any GridColumn

Selection Handling

Name
Description

allowedFillDirections

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

columnSelect

Controls if multiple columns can be selected at once.

columnSelectionBlending

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

drawFocusRing

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

fillHandle

Controls the presence of the fill indicator

gridSelection

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

highlightRegions

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

onGridSelectionChange

Emitted whenever the gridSelection should change.

onSelectionCleared

Emitted when the selection is explicitly cleared.

rangeSelect

Controls if multiple ranges can be selected at once.

rangeSelectionBlending

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

rowSelect

Controls if multiple rows can be selected at aonce.

rowSelectionBlending

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

spanRangeBehavior

Determines if the gridSelection should allow partial spans or not.

Editing

Name
Description

coercePasteValue

Allows coercion of pasted values.

imageEditorOverride

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

onCellEdited

Emitted whenever a cell edit is completed.

onCellsEdited

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

onDelete

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

onFillPattern

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

onFinishedEditing

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

onGroupHeaderRenamed

Emitted whe the user wishes to rename a group.

onPaste

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

onRowAppended

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

trailingRowOptions

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

trapFocus

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

validateCell

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

Name
Description

keybindings

Controls which keybindings are enabled while the grid is selected.

maxColumnAutoWidth

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

maxColumnWidth

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

minColumnWidth

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

onCellActivated

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

onCellClicked

Emitted when a cell is clicked.

onCellContextMenu

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

onColumnMoved

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

onColumnProposeMove

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

onColumnResize

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

onColumnResizeEnd

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

onColumnResizeStart

Emitted when a column resize operation begins.

onGroupHeaderClicked

Emitted when a group header is clicked.

onGroupHeaderContextMenu

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

onHeaderClicked

Emitted when a column header is clicked.

onHeaderContextMenu

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

onHeaderMenuClick

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

onItemHovered

Emitted when the hovered item changes.

onKeyDown

Emitted when a key is pressed.

onKeyUp

Emitted when a key is released.

onMouseMove

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

onRowMoved

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

preventDiagonalScrolling

Prevents diagonal scrolling

rowSelectionMode

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

Drag and Drop

Name
Description

onDragLeave

Emitted when an external drag event exits the drop region.

onDragOverCell

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

onDrop

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

Custom Cells

Name
Description

customRenderers

FIXME

drawCell

Callback used to override the rendering of any cell.

drawHeader

Callback used to override the rendering of any header.

Rarely Used

Name
Description

experimental

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

imageWindowLoader

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.

initialSize

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.

isDraggable

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

isOutsideClick

Allows bypassing the default outside click handler for overlay editors.

onDragStart

Emitted when a drag starts and isDraggable is true.

scrollOffsetX

Sets the initial scroll offset in the x direction.

scrollOffsetY

Sets the initial scroll offset in the y direction.

PreviousAPINextRequired Props

Last updated