React DataGrid API
The DataGrid is a widget that represents data from a local or remote source in the form of a grid. This widget offers such basic features as sorting, grouping, filtering, as well as more advanced capabilities, like state storing, export to Excel, master-detail interface, and many others.
See Also
- Set Up DevExtreme: Angular | Vue | React | jQuery | AngularJS | Knockout | ASP.NET MVC 5 | ASP.NET Core
- Configure a Widget: Angular | Vue | React | jQuery | AngularJS | Knockout | ASP.NET MVC 5 | ASP.NET Core
Props
This section describes the configuration options of the DataGrid widget.
| Name | Description |
|---|---|
| accessKey | Specifies the shortcut key that sets focus on the widget. |
| activeStateEnabled | Specifies whether or not the widget changes its state when interacting with a user. |
| allowColumnReordering | Specifies whether a user can reorder columns. |
| allowColumnResizing | Specifies whether a user can resize columns. |
| cacheEnabled | Specifies whether data should be cached. |
| cellHintEnabled | Enables a hint that appears when a user hovers the mouse pointer over a cell with truncated content. |
| columnAutoWidth | Specifies whether columns should adjust their widths to the content. |
| columnChooser | Configures the column chooser. |
| columnFixing | Configures column fixing. |
| columnHidingEnabled | Specifies whether the widget should hide columns to adapt to the screen or container size. Ignored if allowColumnResizing is true and columnResizingMode is "widget". |
| columnMinWidth | Specifies the minimum width of columns. |
| columnResizingMode | Specifies how the widget resizes columns. Applies only if allowColumnResizing is true. |
| columns | An array of grid columns. |
| columnWidth | Specifies the width for all data columns. Has a lower priority than the column.width option. |
| customizeColumns | Customizes columns after they are created. |
| customizeExportData | Customizes data before export. You can use the export.customizeExcelCell function instead. |
| dataSource | Binds the widget to data. |
| dateSerializationFormat | Specifies the format in which date-time values should be sent to the server. Use it only if you do not specify the dataSource at design time. |
| disabled | Specifies whether the widget responds to user interaction. |
| editing | Configures editing. |
| elementAttr | Specifies the attributes to be attached to the widget's root element. |
| errorRowEnabled | Indicates whether to show the error row. |
| export | Configures client-side exporting. |
| filterBuilder | Configures the integrated filter builder. |
| filterBuilderPopup | Configures the popup in which the integrated filter builder is shown. |
| filterPanel | Configures the filter panel. |
| filterRow | Configures the filter row. |
| filterSyncEnabled | Specifies whether to synchronize the filter row, header filter, and filter builder. The synchronized filter expression is stored in the filterValue option. |
| filterValue | Specifies a filter expression. |
| focusedColumnIndex | Specifies the index of the column focused initially or currently in the data row area. |
| focusedRowEnabled | Specifies whether the focused row feature is enabled. |
| focusedRowIndex | Specifies the initially or currently focused grid row's index. Use it when focusedRowEnabled is true. |
| focusedRowKey | Specifies initially or currently focused grid row's key. Use it when focusedRowEnabled is true. |
| focusStateEnabled | Specifies whether the widget can be focused using keyboard navigation. |
| grouping | Configures grouping. |
| groupPanel | Configures the group panel. |
| headerFilter | Configures the header filter feature. |
| height | Specifies the widget's height. |
| highlightChanges | Specifies whether to highlight rows and cells with edited data. repaintChangesOnly should be true. |
| hint | Specifies text for a hint that appears when a user pauses on the widget. |
| hoverStateEnabled | Specifies whether to highlight rows when a user moves the mouse pointer over them. |
| keyboardNavigation | Configures keyboard navigation. |
| keyExpr | Specifies which data field provides keys for data items. Applies only if data is a simple array. |
| loadPanel | Configures the load panel. |
| masterDetail | Allows you to build a master-detail interface in the grid. |
| noDataText | Specifies text shown when the widget does not display any data. |
| onAdaptiveDetailRowPreparing | A function that is executed before an adaptive detail row is rendered. |
| onCellClick | A function that is executed when a cell is clicked or tapped. Executed before onRowClick. |
| onCellDblClick | A function that is executed when a cell is double-clicked or double-tapped. Executed before onRowDblClick. |
| onCellHoverChanged | A function that is executed after the pointer enters or leaves a cell. |
| onCellPrepared | A function that is executed after a cell is created. |
| onContentReady | A function that is executed when the widget's content is ready and each time the content is changed. |
| onContextMenuPreparing | A function that is executed before the context menu is rendered. |
| onDataErrorOccurred | A function that is executed when an error occurs in the data source. |
| onDisposing | A function that is executed before the widget is disposed of. |
| onEditingStart | A function that is executed before a cell or row switches to the editing state. |
| onEditorPrepared | A function that is executed after an editor is created. Not executed for cells with an editCellTemplate. |
| onEditorPreparing | A function used to customize or replace default editors. Not executed for cells with an editCellTemplate. |
| onExported | A function that is executed after data is exported. |
| onExporting | A function that is executed before data is exported. |
| onFileSaving | A function that is executed before a file with exported data is saved to the user's local storage. |
| onFocusedCellChanged | A function that is executed after the focused cell changes. |
| onFocusedCellChanging | A function that is executed before the focused cell changes. |
| onFocusedRowChanged | A function that is executed after the focused row changes. Applies only when focusedRowEnabled is true. |
| onFocusedRowChanging | A function that is executed before the focused row changes. Applies only when focusedRowEnabled is true. |
| onInitialized | A function used in JavaScript frameworks to save the widget instance. |
| onInitNewRow | A function that is executed before a new row is added to the widget. |
| onKeyDown | A function that is executed when the widget is in focus and a key has been pressed down. |
| onOptionChanged | A function that is executed after a widget option is changed. |
| onRowClick | A function that is executed when a row is clicked or tapped. |
| onRowCollapsed | A function that is executed after a row is collapsed. |
| onRowCollapsing | A function that is executed before a row is collapsed. |
| onRowDblClick | A function that is executed when a row is double-clicked or double-tapped. Executed after onCellDblClick. |
| onRowExpanded | A function that is executed after a row is expanded. |
| onRowExpanding | A function that is executed before a row is expanded. |
| onRowInserted | A function that is executed after a new row has been inserted into the data source. |
| onRowInserting | A function that is executed before a new row is inserted into the data source. |
| onRowPrepared | A function that is executed after a row is created. |
| onRowRemoved | A function that is executed after a row has been removed from the data source. |
| onRowRemoving | A function that is executed before a row is removed from the data source. |
| onRowUpdated | A function that is executed after a row has been updated in the data source. |
| onRowUpdating | A function that is executed before a row is updated in the data source. |
| onRowValidating | A function that is executed after cells in a row are validated against validation rules. |
| onSelectionChanged | A function that is executed after selecting a row or clearing its selection. |
| onToolbarPreparing | A function that is executed before the toolbar is created. |
| pager | Configures the pager. |
| paging | Configures paging. |
| remoteOperations | Notifies the DataGrid of the server's data processing operations. |
| renderAsync | Specifies whether to render the filter row, command columns, and columns with showEditorAlways set to true after other elements. |
| repaintChangesOnly | Specifies whether to repaint only those cells whose data changed. |
| rowAlternationEnabled | Specifies whether rows should be shaded differently. |
| rowComponent | An alias for the rowTemplate option specified in React. Accepts a custom component. Refer to Using a Custom Component for more information. |
| rowRender | An alias for the rowTemplate option specified in React. Accepts a rendering function. Refer to Using a Rendering Function for more information. |
| rowTemplate | Specifies a custom template for rows. |
| rtlEnabled | Switches the widget to a right-to-left representation. |
| scrolling | Configures scrolling. |
| searchPanel | Configures the search panel. |
| selectedRowKeys | Allows you to select rows or determine which rows are selected. Applies only if selection.deferred is false. |
| selection | Configures runtime selection. |
| selectionFilter | Specifies filters for the rows that must be selected initially. Applies only if selection.deferred is true. |
| showBorders | Specifies whether the outer borders of the widget are visible. |
| showColumnHeaders | Specifies whether column headers are visible. |
| showColumnLines | Specifies whether vertical lines that separate one column from another are visible. |
| showRowLines | Specifies whether horizontal lines that separate one row from another are visible. |
| sortByGroupSummaryInfo | Allows you to sort groups according to the values of group summary items. |
| sorting | Configures runtime sorting. |
| stateStoring | Configures state storing. |
| summary | Specifies the options of the grid summary. |
| tabIndex | Specifies the number of the element when the Tab key is used for navigating. |
| twoWayBindingEnabled | Specifies whether to enable two-way data binding. |
| visible | Specifies whether the widget is visible. |
| width | Specifies the widget's width. |
| wordWrapEnabled | Specifies whether text that does not fit into a column should be wrapped. |
See Also
- Configure a Widget: Angular | Vue | React | jQuery | AngularJS | Knockout | ASP.NET MVC 5 | ASP.NET Core
Methods
This section describes the methods that can be used to manipulate the DataGrid widget.
| Name | Description |
|---|---|
| addColumn(columnOptions) | Adds a new column. |
| addRow() | Adds an empty data row. |
| beginCustomLoading(messageText) | Shows the load panel. |
| beginUpdate() | Prevents the widget from refreshing until the endUpdate() method is called. |
| byKey(key) | Gets a data object with a specific key. |
| cancelEditData() | Discards changes that a user made to data. |
| cellValue(rowIndex, dataField) | Gets the value of a cell with a specific row index and a data field, column caption or name. |
| cellValue(rowIndex, dataField, value) | Sets a new value to a cell with a specific row index and a data field, column caption or name. |
| cellValue(rowIndex, visibleColumnIndex) | Gets the value of a cell with specific row and column indexes. |
| cellValue(rowIndex, visibleColumnIndex, value) | Sets a new value to a cell with specific row and column indexes. |
| clearFilter() | Clears all filters applied to widget rows. |
| clearFilter(filterName) | Clears all row filters of a specific type. |
| clearGrouping() | Ungroups grid records. |
| clearSelection() | Clears selection of all rows on all pages. |
| clearSorting() | Clears sorting settings of all columns at once. |
| closeEditCell() | Switches the cell being edited back to the normal state. Takes effect only if editing.mode is batch and showEditorAlways is false. |
| collapseAdaptiveDetailRow() | Collapses the currently expanded adaptive detail row (if there is one). |
| collapseAll(groupIndex) | Collapses master rows or groups of a specific level. |
| collapseRow(key) | Collapses a group or a master row with a specific key. |
| columnCount() | Gets the data column count. Includes visible and hidden columns, excludes command columns. |
| columnOption(id) | Gets all options of a column with a specific identifier. |
| columnOption(id, optionName) | Gets the value of a single column option. |
| columnOption(id, optionName, optionValue) | Updates the value of a single column option. |
| columnOption(id, options) | Updates the values of several column options. |
| defaultOptions(rule) | Specifies the device-dependent default configuration options for this component. |
| deleteColumn(id) | Removes a column. |
| deleteRow(rowIndex) | Removes a row with a specific index. |
| deselectAll() | Clears the selection of all rows on all pages or the currently rendered page only. |
| deselectRows(keys) | Cancels the selection of rows with specific keys. |
| dispose() | Disposes of all the resources allocated to the DataGrid instance. |
| editCell(rowIndex, dataField) | Switches a cell with a specific row index and a data field to the editing state. Takes effect only if the editing mode is "batch" or "cell". |
| editCell(rowIndex, visibleColumnIndex) | Switches a cell with specific row and column indexes to the editing state. Takes effect only if the editing mode is "batch" or "cell". |
| editRow(rowIndex) | Switches a row with a specific index to the editing state. Takes effect only if the editing mode is "row", "popup" or "form". |
| element() | Gets the root widget element. |
| endCustomLoading() | Hides the load panel. |
| endUpdate() | Refreshes the widget after a call of the beginUpdate() method. |
| expandAdaptiveDetailRow(key) | Expands an adaptive detail row. |
| expandAll(groupIndex) | Expands master rows or groups of a specific level. Does not apply if data is remote. |
| expandRow(key) | Expands a group or a master row with a specific key. |
| exportToExcel(selectionOnly) | Exports grid data to Excel. |
| filter() | Gets a filter expression applied to the widget's data source using the filter(filterExpr) method and the DataSource's filter option. |
| filter(filterExpr) | Applies a filter to the widget's data source. |
| focus() | Sets focus on the widget. |
| focus(element) | Sets focus on a specific cell. |
| getCellElement(rowIndex, dataField) | Gets a cell with a specific row index and a data field, column caption or name. |
| getCellElement(rowIndex, visibleColumnIndex) | Gets a cell with specific row and column indexes. |
| getCombinedFilter() | Gets the total filter that combines all the filters applied. |
| getCombinedFilter(returnDataField) | Gets the total filter that combines all the filters applied. |
| getDataSource() | Gets the DataSource instance. |
| getInstance(element) | Gets the instance of a widget found using its DOM node. |
| getKeyByRowIndex(rowIndex) | Gets the key of a row with a specific index. |
| getRowElement(rowIndex) | Gets the container of a row with a specific index. |
| getRowIndexByKey(key) | Gets the index of a row with a specific key. |
| getScrollable() | Gets the instance of the widget's scrollable part. |
| getSelectedRowKeys() | Gets the currently selected rows' keys. |
| getSelectedRowsData() | Gets the selected rows' data objects. |
| getTotalSummaryValue(summaryItemName) | Gets the value of a total summary item. |
| getVisibleColumns() | Gets all visible columns. |
| getVisibleColumns(headerLevel) | Gets all visible columns at a specific hierarchical level of column headers. Use it to access banded columns. |
| getVisibleRows() | Gets currently rendered rows. |
| hasEditData() | Checks whether the widget has unsaved changes. |
| hideColumnChooser() | Hides the column chooser. |
| instance() | Gets the widget's instance. Use it to access other methods of the widget. |
| isAdaptiveDetailRowExpanded(key) | Checks whether an adaptive detail row is expanded or collapsed. |
| isRowExpanded(key) | Checks whether a specific group or master row is expanded or collapsed. |
| isRowFocused(key) | Checks whether a row with a specific key is focused. |
| isRowSelected(data) | Checks whether a row found using its data object is selected. Takes effect only if selection.deferred is true. |
| isRowSelected(key) | Checks whether a row with a specific key is selected. Takes effect only if selection.deferred is false. |
| keyOf(obj) | Gets a data object's key. |
| navigateToRow(key) | Navigates the grid to the data page that contains the row with the specified key and scrolls the grid to display the row if it is not in the viewport. |
| off(eventName) | Detaches all event handlers from a single event. |
| off(eventName, eventHandler) | Detaches a particular event handler from a single event. |
| on(eventName, eventHandler) | Subscribes to an event. |
| on(events) | Subscribes to events. |
| option() | Gets all widget options. |
| option(optionName) | Gets the value of a single option. |
| option(optionName, optionValue) | Updates the value of a single option. |
| option(options) | Updates the values of several options. |
| pageCount() | Gets the total page count. |
| pageIndex() | Gets the current page index. |
| pageIndex(newIndex) | Switches the widget to a specific page using a zero-based index. |
| pageSize() | Gets the current page size. |
| pageSize(value) | Sets the page size. |
| refresh() | Reloads data and repaints the widget. |
| refresh(changesOnly) | Reloads data and repaints the widget or elements whose data changed. |
| repaint() | Repaints the widget without reloading data. Call it to update the widget's markup. |
| repaintRows(rowIndexes) | Repaints specific rows. |
| saveEditData() | Saves changes that a user made to data. |
| searchByText(text) | Seeks a search string in the columns whose allowSearch option is true. |
| selectAll() | Selects all rows. |
| selectRows(keys, preserve) | Selects rows with specific keys. |
| selectRowsByIndexes(indexes) | Selects rows with specific indexes. |
| showColumnChooser() | Shows the column chooser. |
| state() | Gets the current widget state. |
| state(state) | Sets the widget state. |
| totalCount() | Gets the total row count. |
| undeleteRow(rowIndex) | Recovers a row deleted in batch editing mode. |
| updateDimensions() | Updates the widget's content after resizing. |
See Also
- Call Methods: Angular | Vue | React | jQuery | AngularJS | Knockout | ASP.NET MVC 5 | ASP.NET Core
Events
This section describes events fired by this widget.
| Name | Description |
|---|---|
| adaptiveDetailRowPreparing | Raised before an adaptive detail row is rendered. |
| cellClick | Raised when a cell is clicked or tapped. |
| cellDblClick | Raised when a cell is double-clicked or double-tapped. |
| cellHoverChanged | Raised after the pointer enters or leaves a cell. |
| cellPrepared | Raised after a cell is created. |
| contentReady | Raised when the widget's content is ready. |
| contextMenuPreparing | Raised before the context menu is rendered. |
| dataErrorOccurred | Raised when an error occurs in the data source. |
| disposing | Raised before the widget is disposed of. |
| editingStart | Raised before a cell or row switches to the editing state. |
| editorPrepared | Raised after an editor is created. |
| editorPreparing | Raised before an editor is created. |
| exported | Raised after data is exported. |
| exporting | Raised before data is exported. |
| fileSaving | Raised before a file with exported data is saved to the user's local storage. |
| focusedCellChanged | Raised after the focused cell changes. |
| focusedCellChanging | Raised before the focused cell changes. |
| focusedRowChanged | Raised after the focused row changes. Applies only when focusedRowEnabled is true. |
| focusedRowChanging | Raised before the focused row changes. Applies only when focusedRowEnabled is true. |
| initialized | Raised only once, after the widget is initialized. |
| initNewRow | Raised before a new row is added to the widget. |
| keyDown | Raised when the widget is in focus and a key has been pressed down. |
| optionChanged | Raised after a widget option is changed. |
| rowClick | Raised when a row is clicked or tapped. |
| rowCollapsed | Raised after a row is collapsed. |
| rowCollapsing | Raised before a row is collapsed. |
| rowDblClick | Raised when a row is double-clicked or double-tapped. |
| rowExpanded | Raised after a row is expanded. |
| rowExpanding | Raised before a row is expanded. |
| rowInserted | Raised after a new row has been inserted into the data source. |
| rowInserting | Raised before a new row is inserted into the data source. |
| rowPrepared | Raised after a row is created. |
| rowRemoved | Raised after a row has been removed from the data source. |
| rowRemoving | Raised before a row is removed from the data source. |
| rowUpdated | Raised after a row has been updated in the data source. |
| rowUpdating | Raised before a row is updated in the data source. |
| rowValidating | Raised after cells in a row are validated against validation rules. |
| selectionChanged | Raised after selecting a row or clearing its selection. |
| toolbarPreparing | Raised before the toolbar is created. |
See Also
- Handle Events: Angular | Vue | React | jQuery | AngularJS | Knockout | ASP.NET MVC 5 | ASP.NET Core
Row
This section describes the properties of a grid row. An object containing these properties comes to certain event-handling functions.
If you have technical questions, please create a support ticket in the DevExpress Support Center.