``` or you can create a portal element yourself using the `createPortal` function from `react-dom` and pass it to the DataEditor via the `portalElementRef` prop. ```jsx const portalRef = useRef(null); <> { createPortal(

, document.body ) } ``` Once you've got that done, the easiest way to use the Data Grid is to give it a fixed size: ```jsx ``` ## 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. Note that there is currently no way to tell the grid that data has changed. It has to be forced to redraw by passing a different object to the `getCellContent` property. This triggers the entire grid to redraw. You should avoid changing the `getCellContent` object ID as much as possible otherwise. If you want to use the default Image overlay preview you must remember to include the react-responsive-carousel css file or it will not function correctly. This should be available in your node-modules. ```ts import "react-responsive-carousel/lib/styles/carousel.min.css"; ``` ## A note on col/row values Grid always passes col/row coordinate pairs in the format [col, row] and never [row, col]. This is to more accurately match an [x, y] world, even though most english speakers will tend to say "row col". # API Overview Details of each property can be found by clicking on it. ## Types | Name | Description | | ------------------------------- | --------------------------------------------------------------------- | | [GridColumn](#gridcolumn) | A column description. Passed to the `columns` property. | | [GridCell](#gridcell) | The basic interface for defining a cell | | [GridSelection](#gridselection) | The most basic representation of the selected cells in the data grid. | | [Theme](#theme) | The theme used by the data grid to get all color and font information | ## Ref Methods | Name | Description | | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | [appendRow](#appendrow) | Append a row to the data grid. | | [appendColumn](#appendcolumn) | Append a column to the data grid. | | [emit](#emit) | Used to emit commands normally emitted by keyboard shortcuts. | | [focus](#focus) | Focuses the data grid. | | [getBounds](#getbounds) | Gets the current screen-space bounds of a desired cell. | | [remeasureColumns](#remeasurecolumns) | Causes the columns in the selection to have their natural sizes recomputed and re-emitted as a resize event. | | [scrollTo](#scrollto) | Tells the data-grid to scroll to a particular location. | | [updateCells](#updatecells) | Invalidates the rendering of a list of passed cells. | | [getMouseArgsForPosition](#getmouseargsforposition) | Gets the mouse args from pointer event position. | | [aiFill](#dataeditorrefaifill) | AI Fill's API, on a grid with the `aiFill` prop once AI Fill has loaded; `undefined` otherwise. | ## 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](#columns) | All columns in the data grid. | | [getCellContent](#getcellcontent) | A callback to get the content of a given cell location. | | [rows](#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 | |---------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [aiFill](#quick-start-aifill-prop) | Turns on AI Fill: AI-filled columns powered by Jev, with suggestions, review, accept and undo. Unset, the grid is unchanged and no AI code loads. See [AI Fill](#ai-fill). | | [fixedShadowX](#fixedshadow) | Enable/disable a shadow behind fixed columns on the X axis. | | [fixedShadowY](#fixedshadow) | Enable/disable a shadow behind the header(s) on the Y axis. | | [freezeColumns](#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. | | [getCellsForSelection](#getcellsforselection) | Used to fetch large amounts of cells at once. Used for copy/paste, if unset copy will not work. | | [markdownDivCreateNode](#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](#onvisibleregionchanged) | Emits whenever the visible rows/columns changes. | | [provideEditor](#provideeditor) | Callback for providing a custom editor for a cell. | | [portalElementRef](#portalelementref) | A ref to the portal element to use for the overlay editor. | | [rowHeight](#rowheight) | Callback or number used to specify the height of a given row. | | [rowMarkers](#rowmarkers) | Enable/disable row marker column on the left. Can show row numbers, selection boxes, or both. | | [smoothScrollX](#smoothscroll) | Enable/disable smooth scrolling on the X axis. | | [smoothScrollY](#smoothscroll) | Enable/disable smooth scrolling on the Y axis. | ## Search | Name | Description | | ------------------------------------------------- | ------------------------------------------------------------------------------------- | | [onSearchClose](#onsearchclose) | Emitted when the search interface close button is clicked. | | [onSearchResultsChanged](#onsearchresultschanged) | Emitted when the search results change. | | [onSearchValueChange](#onsearchvaluechange) | Emitted when the user types a new value into the search box. | | [searchResults](#searchresults) | Overrides the search results and highlights all items for the user to enumerate over. | | [searchValue](#searchvalue) | Sets the search value for the search box. | | [showSearch](#showsearch) | Show/hide the search interface. | ## Styling | Name | Description | | ------------------------------------------- | ----------------------------------------------------------------------- | | [getGroupDetails](#getgroupdetails) | Callback to provide additional details for group headers such as icons. | | [getRowThemeOverride](#getrowthemeoverride) | Callback to provide theme override for any row. | | [groupHeaderHeight](#groupheaderheight) | The height in pixels of the column group headers. | | [headerHeight](#headerheight) | The height in pixels of the column headers. | | [headerIcons](#headericons) | Additional header icons for use by `GridColumn`. | | [overscrollX](#overscroll) | Allows overscrolling the data grid horizontally by a set amount. | | [overscrollY](#overscroll) | Allows overscrolling the data grid vertically by a set amount. | | [rightElement](#rightelement) | A node which will be placed at the right edge of the data grid. | | [rightElementProps](#rightelement) | Changes how the right element renders. | | [rowMarkerStartIndex](#rowmarkerstartindex) | The index of the first element in the grid | | [rowMarkerTheme](#rowmarkertheme) | Overrides the theme for row markers | | [rowMarkerWidth](#rowmarkerwidth) | The width of the row markers. | | [scaleToRem](#scaletorem) | Scales most elements in the theme to match rem scaling automatically | | [verticalBorder](#verticalborder) | Enable/disable vertical borders for any `GridColumn` | ## Selection Handling | Name | Description | | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | [columnSelect](#rangeselect) | Controls if multiple columns can be selected at once. | | [columnSelectionBlending](#rangeselectionblending) | Controls how column selections may be mixed with other selection types. | | [drawFocusRing](#drawfocusring) | Determins if the focus ring should be drawn by the grid. | | [fillHandle](#fillhandle) | Controls the presence of the fill indicator | | [gridSelection](#gridselection) | The current selection active in the data grid. Includes both the selection cell and the selected range. | | [highlightRegions](#highlightregions) | Adds additional highlights to the data grid for showing contextually important cells. | | [onGridSelectionChange](#gridselection) | Emitted whenever the `gridSelection` should change. | | [onSelectionCleared](#onselectioncleared) | Emitted when the selection is explicitly cleared. | | [rangeSelect](#rangeselect) | Controls if multiple ranges can be selected at once. | | [rangeSelectionBlending](#rangeselectionblending) | Controls how range selections may be mixed with other selection types. | | [rowSelect](#rangeselect) | Controls if multiple rows can be selected at aonce. | | [rowSelectionBlending](#rangeselectionblending) | Controls how row selections may be mixed with other selection types. | | [spanRangeBehavior](#spanrangebehavior) | Determines if the `gridSelection` should allow partial spans or not. | ## Editing | Name | Description | | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | [coercePasteValue](#coercepastevalue) | Allows coercion of pasted values. | | [imageEditorOverride](#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](#oncelledited) | Emitted whenever a cell edit is completed. | | [onCellsEdited](#oncelledited) | Emitted whenever a cell edit is completed and provides all edits inbound as a single batch. | | [onDelete](#ondelete) | Emitted whenever the user has requested the deletion of the selection. | | [onFillPattern](#onfillpattern) | Emitted when the fill handle is used to replace the contents of a region of the grid. | | [onFinishedEditing](#onfinishedediting) | Emitted when editing has finished, regardless of data changing or not. | | [onGroupHeaderRenamed](#ongroupheaderrenamed) | Emitted whe the user wishes to rename a group. | | [onPaste](#onpaste) | Emitted any time data is pasted to the grid. Allows controlling paste behavior. | | [onRowAppended](#trailingrowoptions) | Emitted whenever a row append operation is requested. Append location can be set in callback. | | [onColumnAppended](#oncolumnappended) | Emitted whenever a column append operation is requested. Append location can be set in callback. | | [trailingRowOptions](#trailingrowoptions) | Controls the built in trailing row to allow appending new rows. | ## Input Interaction | Name | Description | | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [keybindings](#keybindings) | Controls which keybindings are enabled while the grid is selected. | | [maxColumnAutoWidth](#maxcolumnwidth) | Sets the maximum width a column can be auto-sized to. | | [maxColumnWidth](#maxcolumnwidth) | Sets the maximum width the user can resize a column to. | | [minColumnWidth](#maxcolumnwidth) | Sets the minimum width the user can resize a column to. | | [onCellActivated](#oncellactivated) | Emitted when a cell is activated, such as by pressing Enter, Space, double clicking, or typing. | | [onCellClicked](#oncellclicked) | Emitted when a cell is clicked. | | [onCellContextMenu](#oncellcontextmenu) | Emitted when a cell should show a context menu. Usually right click. | | [onColumnMoved](#oncolumnmoved) | Emitted when a column has been dragged to a new location. | | [onColumnResize](#oncolumnresize) | Emitted when a column has been resized to a new size. | | [onColumnResizeEnd](#oncolumnresize) | Emitted when a column has been resized to a new size and the user has stopped interacting wtih the resize handle. | | [onGroupHeaderClicked](#ongroupheaderclicked) | Emitted when a group header is clicked. | | [onGroupHeaderContextMenu](#ongroupheadercontextmenu) | Emitted when a group header should show a context menu. Usually right click. | | [onHeaderClicked](#onheaderclicked) | Emitted when a column header is clicked. | | [onHeaderContextMenu](#onheadercontextmenu) | Emitted when a column header should show a context menu. Usually right click. | | [onHeaderMenuClick](#onheadermenuclick) | Emitted when the menu dropdown arrow on a column header is clicked. | | [onItemHovered](#onitemhovered) | Emitted when the hovered item changes. | | [onKeyDown](#onkey) | Emitted when a key is pressed. | | [onKeyUp](#onkey) | Emitted when a key is released. | | [onMouseMove](#onmousemove) | Emitted whenever the mouse moves. Be careful, can cause performance issues. | | [onRowMoved](#onrowmoved) | Emitted when a row has been dragged to a new location. | | [preventDiagonalScrolling](#preventdiagonalscrolling) | Prevents diagonal scrolling | | [rowSelectionMode](#rowselectionmode) | Determines if row selection requires a modifier key to enable multi-selection or not. | | [columnSelectionMode](#columnselectionmode) | Determines if column selection requires a modifier key to enable multi-selection or not. | | [scrollToEnd](#scrolltoend) | When set to true, the grid will scroll to the end. The ref has a better method to do this and this prop should not be used but it will remain supported for the foreseeable future. | | [showMinimap](#showminimap) | Shows the interactive minimap of the grid. | | [validateCell](#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. | ## Drag and Drop | Name | Description | | ------------------------- | ------------------------------------------------------------- | | [onDragLeave](#ondrop) | Emitted when an external drag event exits the drop region. | | [onDragOverCell](#ondrop) | Emitted when an external drag event is started over a cell. | | [onDrop](#ondrop) | Emitted when an external drag event is completed on the grid. | ## Custom Cells | Name | Description | | ---------------------------------- | ------------------------------------------------------ | | [customRenderers](#customRenderer) | Custom renderers for `GridCellKind.Custom`. | | [renderers](#renderers) | Overrides built-in cell renderers. | | [drawCell](#drawcell) | Callback used to override the rendering of any cell. | | [drawHeader](#drawheader) | Callback used to override the rendering of any header. | ## Rarely Used | Name | Description | | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | [experimental](#experimental) | Contains experimental flags. Nothing in here is considered stable API and is mostly used for features that are not yet settled. | | [imageWindowLoader](#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](#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](#isdraggable) | Makes the grid as a whole draggable. Disables many interactions. | | [isOutsideClick](#isoutsideclick) | Allows bypassing the default outside click handler for overlay editors. | | [onDragStart](#isdraggable) | Emitted when a drag starts and `isDraggable` is true. | | [scrollOffsetX](#scrolloffset) | Sets the initial scroll offset in the x direction. | | [scrollOffsetY](#scrolloffset) | Sets the initial scroll offset in the y direction. | # Keybindings | Key Combo | Default | Flag | Description | | ---------------------------- | ------- | ------------------- | ---------------------------------------------------------------------------------------- | | Arrow | ✔️ | N/A | Moves the currently selected cell and clears other selections | | Shift + Arrow | ✔️ | N/A | Extends the current selection range in the direction pressed. | | Alt + Arrow | ✔️ | N/A | Moves the currently selected cell and retains the current selection | | Ctrl/Cmd + Arrow \| Home/End | ✔️ | N/A | Move the selection as far as possible in the direction pressed. | | Ctrl/Cmd + Shift + Arrow | ✔️ | N/A | Extends the selection as far as possible in the direction pressed. | | Shift + Home/End | ✔️ | N/A | Extends the selection as far as possible in the direction pressed. | | Ctrl/Cmd + A | ✔️ | `selectAll` | Selects all cells. | | Shift + Space | ✔️ | `selectRow` | Selecs the current row. | | Ctrl + Space | ✔️ | `selectCol` | Selects the current col. | | PageUp/PageDown | ✔️ | `pageUp`/`pageDown` | Moves the current selection up/down by one page. | | Escape | ✔️ | `clear` | Clear the current selection. | | Ctrl/Cmd + D | ❌ | `downFill` | Data from the first row of the range will be down filled into the rows below it | | Ctrl/Cmd + R | ❌ | `rightFill` | Data from the first column of the range will be right filled into the columns next to it | | Ctrl/Cmd + C | ✔️ | `copy` | Copies the current selection. | | Ctrl/Cmd + V | ✔️ | `paste` | Pastes the current buffer into the grid. | | Ctrl/Cmd + F | ❌ | `search` | Opens the search interface. | | Ctrl/Cmd + Home/End | ✔️ | `first`/`last` | Move the selection to the first/last cell in the data grid. | | Ctrl/Cmd + Shift + Home/End | ✔️ | `first`/`last` | Extend the selection to the first/last cell in the data grid. | # Full API Docs ## GridColumn Grid columns are the basic horizontal building block of the data grid. At their most basic level a `GridColumn` is just an object which contains a `title` and a `width` or `id`. Their type looks like: ```ts interface BaseGridColumn { readonly title: string; readonly group?: string; readonly icon?: GridColumnIcon | string; readonly overlayIcon?: GridColumnIcon | string; readonly hasMenu?: boolean; readonly style?: "normal" | "highlight"; readonly grow?: number; readonly themeOverride?: Partial; readonly trailingRowOptions?: { readonly hint?: string; readonly addIcon?: string; readonly targetColumn?: number | GridColumn; readonly themeOverride?: Partial; readonly disabled?: boolean; }; } interface SizedGridColumn extends BaseGridColumn { readonly width: number; readonly id?: string; } interface AutoGridColumn extends BaseGridColumn { readonly id: string; } export type GridColumn = SizedGridColumn | AutoGridColumn; ``` | Property | Description | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | | title | The title of the column | | group | The name of the group the column belongs to | | icon | The icon the column belongs to. The icon must be either one of the predefined icons or an icon passed to the `headerIcons` prop | | overlayIcon | An icon which is painted on top offset bottom right of the `icon`. Must be a predefined icon or an icon passed to the `headerIcons` prop | | hasMenu | Enables/disables the menu dropdown indicator. If not enabled, `onHeaderMenuClick` will not be emitted. | | style | Makes the column use the highlighted theming from the `Theme`. `themeOverride` can be used to perform the same effect. | | grow | When set to a number > 0 the column will grow to consume extra available space according to the weight of its grow property. | | themeOverride | A `Partial` which can be used to override the theming of the header as well as all cells within the column. | | trailingRowOptions | Overrides the `DataEditor` level prop for [`trailingRowOptions`](#trailingrowoptions) for this column | --- ## GridCell `GridCell` is the basic content building block of a data grid. There are many types of cells available out of the box and more available in additional packages. | Cell Kind | Description | | --------- | -------------------------------------------------------------------------------------------------------------- | | Uri | Displays uris. Can be edited. | | Text | Displays arbitrary text. | | Image | Displays one or more images. | | RowID | Designed to show primary keys in data sources. | | Number | Displays numbers with formatting options and better editing support. | | Bubble | Displays lists of data in little bubbles. | | Boolean | Displays a checkbox which can be directly edited if desired. | | Loading | Useful for when data is loading. Rendering is basically free. | | Markdown | Displays markdown when opened. | | Drilldown | Similar to a bubble cell, but allows embedding text and images with each cell. | | Protected | Displays stars instead of data. Useful for indicating that hidden data is present but unavailable to the user. | | Custom | Has no rendering by default and must be provided via a custom renderer | All grid cells support the following properties ```ts interface BaseGridCell { readonly allowOverlay: boolean; readonly lastUpdated?: number; readonly style?: "normal" | "faded"; readonly themeOverride?: Partial; readonly span?: readonly [number, number]; readonly contentAlign?: "left" | "right" | "center"; readonly cursor?: CSSProperties["cursor"]; } ``` | Property | Description | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | allowOverlay | Determins if an overlay editor or previewer should be shown when activating this cell. | | lastUpdated | If set, the grid will render this cell with a highlighted background which fades out. Uses performance.now() instead of Date.now(). | | style | If set to `faded` the cell will draw with a transparent appearance. | | themeOverride | A partial theme override to use when drawing this cell. | | span | If set the `span` controls which horizontal span a cell belongs to. Spans are inclusive and must be correctly reported for all cells in the span range. | | contentAlign | Changes the default text alignment for the cell. | | cursor | An override for the cell cursor when hovered. | --- ## GridSelection `GridSelection` is the most basic representation of the selected cells, rows, and columns in the data grid. The `current` property accounts for the selected cell and the range of cells selected as well. It is the selection which is modified by keyboard and mouse interaction when clicking on the cells themselves. The `rows` and `columns` properties both account for the columns or rows which have been explicitly selected by the user. Selecting a range which encompases the entire set of cells within a column/row does not implicitly set it into this part of the collection. This allows for distinguishing between cases when the user wishes to delete all contents of a row/column and delete the row/column itself. ```ts interface GridSelection { readonly current?: { readonly cell: Item; readonly range: Readonly; readonly rangeStack: readonly Readonly[]; }; readonly columns: CompactSelection; readonly rows: CompactSelection; } ``` The `cell` is the [col, row] formatted cell which will have the focus ring drawn around it. The `range` should always include the `cell` and represents additional cells which can be edited via copy, delete and other events. The `range` may or may not include partial spans depending on the [`spanRangeBehavior`](#spanrangebehavior) set. --- ## Theme The data grid uses the `Theme` provided to the DataEditer in the `theme` prop. This is used to style editors as well as the grid itself. The theme interface is flat. The data grid comes with a built in theme which it will use to fill in any missing values. | Property | Type | CSS Variable | Description | | --------------------- | ------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------- | | accentColor | string | --gdg-accent-color | The primary accent color of the grid. This will show up in focus rings and selected rows/headers. | | accentFg | string | --gdg-accent-fg | A foreground color which works well on top of the accent color. | | accentLight | string | --gdg-accent-light | A lighter version of the accent color used to hint selection. | | textDark | string | --gdg-text-dark | The standard text color. | | textMedium | string | --gdg-text-medium | A lighter text color used for non-editable data in some cases. | | textLight | string | --gdg-text-light | An even lighter text color | | textBubble | string | --gdg-text-bubble | The text color used in bubbles | | bgIconHeader | string | --gdg-bg-icon-header | The background color for header icons | | fgIconHeader | string | --gdg-fg-icon-header | The foreground color for header icons | | textHeader | string | --gdg-text-header | The header text color | | textGroupHeader | string \| undefined | --gdg-text-group-header | The group header text color, if none provided the `textHeader` is used instead. | | textHeaderSelected | string | --gdg-text-header-selected | The text color used for selected headers | | bgCell | string | --gdg-bg-cell | The primary background color of the data grid. | | bgCellMedium | string | --gdg-bg-cell-medium | Used for disabled or otherwise off colored cells. | | bgHeader | string | --gdg-bg-header | The header background color | | bgHeaderHasFocus | string | --gdg-bg-header-has | The header background color when its column contains the selected cell | | bgHeaderHovered | string | --gdg-bg-header-hovered | The header background color when it is hovered | | bgGroupHeader | string \| undefined | --gdg-bg-group-header | The group header background color, if none provided the `bgHeader` is used instead. | | bgGroupHeaderHovered | string \| undefined | --gdg-bg-group-header-hovered | The group header background color when it is hovered, if none provided the `bgHeaderHovered` is used instead. | | bgBubble | string | --gdg-bg-bubble | The background color used in bubbles | | bgBubbleSelected | string | --gdg-bg-bubble-selected | The background color used in bubbles when the cell is selected | | bgSearchResult | string | --gdg-bg-search-result | The background color used for cells which match the search string | | borderColor | string | --gdg-border-color | The color of all vertical borders and horizontal borders if a horizontal override is not provided | | horizontalBorderColor | string \| undefined | --gdg-horizontal-border-color | The horizontal border color override | | drilldownBorder | string | --gdg-drilldown-border | The ring color of a drilldown cell | | linkColor | string | --gdg-link-color | What color to render links | | cellHorizontalPadding | number | --gdg-cell-horizontal-padding | The internal horizontal padding size of a cell. | | cellVerticalPadding | number | --gdg-cell-vertical-padding | The internal vertical padding size of a cell. | | headerFontStyle | string | --gdg-header-font-style | The font style of the header. e.g. `bold 15px` | | baseFontStyle | string | --gdg-base-font-style | The font style used for cells by default, e.g. `13px` | | fontFamily | string | --gdg-font-family | The font family used by the data grid. | | editorFontSize | string | --gdg-editor-font-size | The font size used by overlay editors. | | lineHeight | number | None | A unitless scaler which defines the height of a line of text relative to the ink size. | | bubbleHeight | number | --gdg-bubble-height | The height (in pixels) of a bubble. | | bubblePadding | number | --gdg-bubble-padding | The left & right padding (in pixels) of a bubble. | | bubbleMargin | number | --gdg-bubble-margin | The margin (in pixels) between bubbles. | | checkboxMaxSize | number | --gdg-checkbox-max-size | The maximum size of checkboxes (in pixels), e.g. for boolean cell and row markers. | | roundingRadius | number \| undefined | --gdg-rounding-radius | The radius of rounded corners used by various grid elements (in pixels). | --- ## updateCells Example usage: ```ts dataGridRef.current.updateCells([{ cell: [10, 10] }, { cell: [11, 10] }, { cell: [12, 10] }]); ``` Causes the data grid to rerender these specific cells. Rerendering a single cell is significantly faster than invalidating the `getCellContent` callback as in the latter case all cells must be redrawn. --- ## getBounds ```ts getBounds: (col?: number, row?: number) => Rectangle | undefined; ``` `getBounds` returns the current bounding box of a cell. This does not need to be a currently rendered cell. If called with `col` and `row` as undefined, the bounding box of the entire data grid scroll area is returned. --- ## scrollTo ```ts scrollTo: ( col: number, row: number, dir?: "horizontal" | "vertical" | "both", paddingX?: number, paddingY?: number, options?: { hAlign?: "start" | "center" | "end"; vAlign?: "start" | "center" | "end"; behavior?: ScrollBehavior; // "auto" | "smooth" | "instant" } ) => void; ``` Requests the data grid to scroll to a particular location. If only one direction is requested it will get as close as it can without scrolling the off axis. Padding can be applied to inset the cell by a certain amount. --- | [focus](#focus) | Focuses the data grid. | | [emit](#emit) | Used to emit commands normally emitted by keyboard shortcuts. | ## appendRow ```ts appendRow: ( col: number, openOverlay: boolean = true, behavior?: ScrollBehavior; // "auto" | "smooth" | "instant" ) => Promise; ``` Appends a row to the data grid. --- ## appendColumn ```ts appendColumn: (row: number, openOverlay?: boolean) => Promise; ``` Appends a column to the data grid. --- ## focus ```ts focus: () => void; ``` Causes the data grid to become focused. --- ## DataEditorRef.aiFill ```ts aiFill?: AIFillApi; ``` AI Fill's API on a grid with the `aiFill` prop, once AI Fill has loaded; `undefined` before that and on a grid without the prop. See [The API](#the-api-aifillapi). --- ## emit ```ts type EmitEvents = "copy" | "paste" | "delete" | "fill-right" | "fill-down"; emit: (eventName: EmitEvents) => Promise; ``` Emits the event into the data grid as if the user had pressed the keyboard shortcut. --- ## getMouseArgsForPosition ```ts getMouseArgsForPosition: (posX: number, posY: number, ev?: MouseEvent | TouchEvent) => GridMouseEventArgs | undefined; ``` Returns grid coordinates and context for a pointer event position. Useful for handling interactions outside of built-in callbacks. --- ## columns ```ts columns: readonly GridColumn[]; ``` `columns` is an array of objects of type `GridColumn` describing the column headers. The length of the array is the number of columns to display. --- ## rows ```ts rows: number; ``` `rows` is the number of rows to display. --- ## getCellContent ```ts getCellContent: (cell: Item) => GridCell; ``` `getCellContent` returns an object of type `GridCell` describing the contents for the cell at the given coordinates. --- ## freezeColumns ```ts freezeColumns?: number; ``` Set to a positive number to freeze columns on the left side of the grid during horizontal scrolling. --- ## getCellsForSelection ```ts type CellArray = readonly (readonly GridCell[])[]; type GetCellsThunk = () => Promise; getCellsForSelection?: true | (selection: Rectangle) => CellArray | GetCellsThunk; ``` `getCellsForSelection` is called when the user copies a selection to the clipboard or the data editor needs to inspect data which may be outside the curently visible range. It must return a two-dimensional array (an array of rows, where each row is an array of cells) of the cells in the selection's rectangle. Note that the rectangle can include cells that are not currently visible. If `true` is passed instead of a callback, the data grid will internally use the `getCellContent` callback to provide a basic implementation of `getCellsForSelection`. This can make it easier to light up more data grid functionality, but may have negative side effects if your data source is not able to handle being queried for data outside the normal window. If `getCellsForSelection` returns a thunk, the data may be loaded asynchronously, however the data grid may be unable to properly react to column spans when performing range selections. Copying large amounts of data out of the grid will depend on the performance of the thunk as well. --- ## markdownDivCreateNode ```ts markdownDivCreateNode?: (content: string) => DocumentFragment; ``` If `markdownDivCreateNode` is specified, then 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 ```ts onVisibleRegionChanged?: ( range: Rectangle, tx: number, ty: number, extras: { selected?: Item; freezeRegion?: Rectangle }; ) => void; ``` `onVisibleRegionChanged` is called whenever the visible region changed. The new visible region is passed as a `Rectangle`. The x and y transforms of the cell region are passed as `tx` and `ty`. The current selection and frozen region are passed in the `extras` object. --- ## provideEditor ```ts export type ProvideEditorComponent = React.FunctionComponent<{ readonly onChange: (newValue: T) => void; readonly onFinishedEditing: (newValue?: T, movement?: readonly [-1 | 0 | 1, -1 | 0 | 1]) => void; readonly isHighlighted: boolean; readonly value: T; readonly initialValue?: string; readonly validatedSelection?: SelectionRange; readonly imageEditorOverride?: ImageEditorType; readonly markdownDivCreateNode?: (content: string) => DocumentFragment; readonly target: Rectangle; readonly forceEditMode: boolean; readonly isValid?: boolean; }>; export type ProvideEditorCallbackResult = | (ProvideEditorComponent & { disablePadding?: boolean; disableStyling?: boolean; }) | ObjectEditorCallbackResult | undefined; export type ProvideEditorCallback = ( cell: T & { location?: Item; activation?: CellActivatedEventArgs } ) => ProvideEditorCallbackResult; provideEditor?: ProvideEditorCallback; ``` When provided the `provideEditor` callbacks job is to be a constructor for functional components which have the correct properties to be used by the data grid as an editor. The editor must implement `onChange` and `onFinishedEditing` callbacks as well support the `isHighlighted` flag which tells the editor to begin with any editable text pre-selected so typing will immediately begin to overwrite it. The `cell` passed to this callback includes a `location` of the activated cell and an `activation` event describing how the editor was opened. --- ## portalElementRef Defaults to div#portal --- ## rowHeight ```ts rowHeight: number | ((index: number) => number); ``` `rowHeight` is the height of a row in the table. It defaults to `34`. By passing a function instead of a number you can give different heights to each row. The `index` is the zero-based absolute row index. --- ## rowMarkers ```ts rowMarkers?: "checkbox" | "number" | "both" | "none"; ``` `rowMarkers` determines whether to display the marker column on the very left. It defaults to `none`. Note that this column doesn't count as a table column, i.e. it has no index, and doesn't change column indexes. --- ## smoothScroll ```ts smoothScrollX?: boolean; smoothScrollY?: boolean; ``` Controls smooth scrolling in the data grid. Defaults to `false`. If smooth scrolling is not enabled the grid will always be cell aligned in the non-smooth scrolling axis. --- ## fixedShadow ```ts fixedShadowX?: boolean; fixedShadowY?: boolean; ``` Controls shadows behind fixed columns and header rows. Defaults to `true`. --- ## showSearch ```ts showSearch?: boolean; ``` `showSearch` causes the search box built into the data grid to become visible. The data grid does not provide an in-built way to show the search box, so it is suggested to hook into the ctrl/cmd+f accelerator or add a button to your apps chrome. --- ## onSearchClose ```ts onSearchClose?: () => void; ``` If `onSearchClose` is not provided and `showSearch` is set to true, the search box will be shown but there will be no close button. Providing an `onSearchClose` callback enables the close button and the event will emit when it is clicked. --- ## searchValue ```ts readonly searchValue?: string; ``` This property is used to set the current search value in the data grid. It accepts a string that represents the term or phrase to be used for searching within the grid. By setting `searchValue`, you can programmatically control the search value. --- ## onSearchResultsChanged ```ts readonly onSearchResultsChanged?: (results: readonly Item[], navIndex: number) => void; ``` This event handler is called when there is a change in the search results of the data grid's search field. It provides two parameters: `results` and `navIndex`. The `results` parameter is an array of `Item` objects, each representing a cell or row that matches the current search query. The `navIndex` parameter is the index of the currently selected or highlighted search result within the `results` array. --- ## onSearchValueChange ```ts readonly onSearchValueChange?: (newVal: string) => void; ``` This event is emitted whenever the search value in the data grid changes. The handler `onSearchValueChange` is provided with a single argument `newVal`, which is the updated string value entered in the search field. Implementing this event allows you to execute custom actions in response to changes in the search input. This can include triggering search operations based on the new value, updating the user interface elements to reflect the change, or any other related functionality that needs to respond to updates in the search term within your data grid. --- ## searchResults ```ts readonly searchResults?: readonly Item[]; ``` This property allows you to specify the search results to be displayed in the data grid. If `searchResults` is not provided, the grid will use its internal search provider to determine and display search results. By setting the `searchResults` property, you can override the default search behavior and supply a custom array of `Item` objects as the search results. These `Item` objects typically refer to the cells or rows in the grid that match a custom search criterion. This is particularly useful if you need to implement a specialized search functionality that differs from the built-in search capabilities of the grid. --- ## drawCell ```ts drawCell?: ( args: { ctx: CanvasRenderingContext2D; cell: GridCell; theme: Theme; rect: Rectangle; col: number; row: number; hoverAmount: number; hoverX: number | undefined; hoverY: number | undefined; highlighted: boolean; imageLoader: ImageWindowLoader; }, drawContent: () => void ) => void; ``` The `drawCell` property enables custom rendering of cells in the Grid. This function is called for each cell during the rendering process and is provided with a comprehensive set of parameters. These parameters include the drawing context (`ctx`), cell data (`cell`), theming details (`theme`), the cell's rectangle (`rect`), column and row indices (`col`, `row`), hover state information (`hoverAmount`, `hoverX`, `hoverY`), a highlight flag (`highlighted`), and an image loader (`imageLoader`). Additionally, `drawCell` provides a `drawContent` method, which, when called, immediately draws the default content of the cell onto the canvas. This design offers flexibility in how you render each cell. For instance, you can first draw a custom background, then call `drawContent` to render the cell's standard contents, and finally add an overlay or additional embellishments. This approach allows for layered rendering, where you can seamlessly integrate custom graphics or styles with the grid's inherent rendering logic. --- ## drawHeader ```ts drawHeader?: (args: { ctx: CanvasRenderingContext2D; column: GridColumn; theme: Theme; rect: Rectangle; hoverAmount: number; hoverX: number | undefined; hoverY: number | undefined; isSelected: boolean; isHovered: boolean; hasSelectedCell: boolean; spriteManager: SpriteManager; menuBounds: Rectangle; }) => boolean; ``` `drawHeader` may be specified to override the rendering of a header. The grid will call this for every header it needs to render. Header rendering is not as well optimized because they do not redraw as often, but very heavy drawing methods can negatively impact horizontal scrolling performance. The return result works the same way as `drawCell`, `false` means the default rendering will happen and `true` means the default rendering will not happen. It is possible to return `false` after rendering just a background and the regular foreground rendering will happen. --- ## renderers ```ts readonly renderers?: readonly InternalCellRenderer[]; ``` An array of cell renderers used when drawing built-in cell types. Provide this prop to override default cell renderers. If omitted, `AllCellRenderers` is used. --- ## getGroupDetails ```ts getGroupDetails?: (groupName: string) => ({ name: string; icon?: string; overrideTheme?: Partial; actions?: { title: string; onClick: (e: GridMouseGroupHeaderEventArgs) => void; icon: GridColumnIcon | string; }[]; }); ``` `getGroupDetails` is invoked whenever a group header is rendered. The group details are used to provide a name override for the group as well as an icon, a list of actions which can be activated by the user, and an overrideTheme which will impact the rendering of all child cells of the group and all column headers in the group. --- ## getRowThemeOverride ```ts getRowThemeOverride?: (row: number) => Partial | undefined; ``` Whenever a row is rendered the row theme override is fetched if provided. This function should aim to be extremely fast as it may be invoked many times per render. All cells in the row have this theme merged into their theme prior to rendering. --- ## groupHeaderHeight ```ts groupHeaderHeight?: number; ``` The height of the group headers in the data grid. If not provided this will default to the [`headerHeight`](#headerheight) value. --- ## headerHeight ```ts headerHeight: number; ``` `headerHeight` is the height of the table header. It defaults to `36`. --- ## headerIcons ```ts headerIcons?: Record string>; ``` Providing custom header icons to the data grid must be done with a somewhat non-standard mechanism to allow theming and scaling. The `headerIcons` property takes a dictionary which maps icon names to functions which can take a foreground and background color and returns back a string representation of an svg. The svg should contain a header similar to this `