All docs
V19.2
24.1
The page you are viewing does not exist in version 24.1.
23.2
The page you are viewing does not exist in version 23.2.
23.1
The page you are viewing does not exist in version 23.1.
22.2
The page you are viewing does not exist in version 22.2.
22.1
The page you are viewing does not exist in version 22.1.
21.2
The page you are viewing does not exist in version 21.2.
21.1
The page you are viewing does not exist in version 21.1.
20.2
The page you are viewing does not exist in version 20.2.
20.1
The page you are viewing does not exist in version 20.1.
19.2
19.1
18.2
18.1
17.2
A newer version of this page is available. Switch to the current version.

jQuery 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.

import DataGrid from "devextreme/ui/data_grid"
Type:

Object

Configuration

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.

autoNavigateToFocusedRow

Automatically scrolls to the focused row when the focusedRowKey is changed.

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

The index of the column that contains the focused data cell.

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 the key property (or properties) that provide(s) key values to access data items. Each key value must be unique. This option 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 a cell's editor. 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. Applies only to cells in data or group rows.

onFocusedCellChanging

A function that is executed before the focused cell changes. Applies only to cells in data or group rows.

onFocusedRowChanged

A function that is executed after the focused row changes. Applies only to data or group rows. focusedRowEnabled should be true.

onFocusedRowChanging

A function that is executed before the focused row changes. Applies only to data or group rows. focusedRowEnabled should be 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 property specified in React. Accepts a custom component. Refer to Using a Custom Component for more information.

rowDragging

Configures row reordering using drag and drop gestures.

rowRender

An alias for the rowTemplate property 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

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 and switches it to the editing state.

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.

getVisibleColumnIndex(id)

Gets the index of a visible column.

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.

resetOption(optionName)

Resets an option to its default value.

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

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

Row

A grid row.

Type:

Object

You can access grid rows using the getVisibleRows() method and within some event handlers, for example, onCellClick, onCellPrepared, onEditorPreparing.