JavaScript/jQuery DataGrid API
The DataGrid is a UI component that represents data from a local or remote source in the form of a grid. This UI component offers such basic features as sorting, grouping, filtering, as well as more advanced capabilities, like state storing, client-side exporting, master-detail interface, and many others.
See Also
jQuery
Angular
Vue
React
Options
This section describes the configuration properties of the DataGrid UI component.
| Name | Description | 
|---|---|
| accessKey | Specifies the shortcut key that sets focus on the UI component. | 
| activeStateEnabled | Specifies whether the UI component changes its visual state as a result of user interaction. | 
| allowColumnReordering | Specifies whether a user can reorder columns. | 
| allowColumnResizing | Specifies whether a user can resize columns. | 
| autoNavigateToFocusedRow | Automatically scrolls the component to the focused row when the focusedRowKey is changed. Incompatible with infinite scrolling mode. | 
| 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 if the component adjusts column widths to fit content. | 
| columnChooser | Configures the column chooser. | 
| columnFixing | Configures column fixing. | 
| columnHidingEnabled | Specifies whether the UI component 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 UI component 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 property. | 
| customizeColumns | Customizes columns after they are created. | 
| dataRowComponent | An alias for the dataRowTemplate property specified in React. Accepts a custom component. Refer to Using a Custom Component for more information. | 
| dataRowRender | An alias for the dataRowTemplate property specified in React. Accepts a rendering function. Refer to Using a Rendering Function for more information. | 
| dataRowTemplate | Specifies a custom template for data rows. | 
| dataSource | Binds the UI component to data. | 
| dateSerializationFormat | Specifies the format in which date-time values should be sent to the server. | 
| disabled | Specifies whether the UI component responds to user interaction. | 
| editing | Configures editing. | 
| elementAttr | Specifies the global attributes to be attached to the UI component's container 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 property. | 
| filterValue | Specifies a filter expression. | 
| focusedColumnIndex | The index of the column that contains the focused data cell. This index is taken from the columns array. | 
| focusedRowEnabled | Specifies whether the focused row feature is enabled. | 
| focusedRowIndex | Specifies or indicates the focused data row's index. | 
| focusedRowKey | Specifies initially or currently focused grid row's key. | 
| grouping | Configures grouping. | 
| groupPanel | Configures the group panel. | 
| headerFilter | Configures the header filter feature. | 
| height | Specifies the UI component'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 UI component. | 
| 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 property 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 a text string shown when the DataGrid 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 grid cell is created. | 
| onContentReady | A function that is executed when the UI component is rendered and each time the component is repainted. | 
| 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 UI component is disposed of. | 
| onEditCanceled | A function that is executed after row changes are discarded. | 
| onEditCanceling | A function that is executed when the edit operation is canceled, but row changes are not yet discarded. | 
| 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 cell editors. Not executed for cells with an editCellTemplate. | 
| onExporting | A function that is executed before data is exported. | 
| 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 UI component instance. | 
| onInitNewRow | A function that is executed before a new row is added to the UI component. | 
| onKeyDown | A function that is executed when the UI component is in focus and a key has been pressed down. | 
| onOptionChanged | A function that is executed after a UI component property 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. | 
| onSaved | A function that is executed after row changes are saved. | 
| onSaving | A function that is executed before pending row changes are saved. | 
| 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 | Specifies DataGrid operations to be executed on the server side. | 
| 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. | 
| rowDragging | Configures row reordering using drag and drop gestures. | 
| rtlEnabled | Switches the UI component 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 UI component 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 properties of the grid summary. | 
| syncLookupFilterValues | Specifies whether to show only relevant values in the header filter and filter row. | 
| tabIndex | Specifies the number of the element when the Tab key is used for navigating. | 
| toolbar | Configures the toolbar. | 
| twoWayBindingEnabled | Specifies whether to enable two-way data binding. | 
| visible | Specifies whether the UI component is visible. | 
| width | Specifies the UI component'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 UI component.
| 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() | Postpones rendering that can negatively affect performance 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 UI component 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 or cell 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 properties of a column with a specific identifier. | 
| columnOption(id, optionName) | Gets the value of a single column property. | 
| columnOption(id, optionName, optionValue) | Updates the value of a single column property. | 
| columnOption(id, options) | Updates the values of several column properties. | 
| defaultOptions(rule) | Specifies the device-dependent default configuration properties 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 UI component element. | 
| endCustomLoading() | Hides the load panel. | 
| endUpdate() | Refreshes the UI component 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. | 
| filter() | Gets a filter expression applied to the UI component's data source using the filter(filterExpr) method and the DataSource's filter property. | 
| filter(filterExpr) | Applies a filter to the dataSource. | 
| focus() | Sets focus on the UI component. | 
| 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 UI component 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 UI component'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 UI component has unsaved changes. | 
| hideColumnChooser() | Hides the column chooser. | 
| instance() | Gets the UI component's instance. Use it to access other methods of the UI component. | 
| 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 to a row with the specified key. | 
| 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 UI component properties. | 
| option(optionName) | Gets the value of a single property. | 
| option(optionName, optionValue) | Updates the value of a single property. | 
| option(options) | Updates the values of several properties. | 
| pageCount() | Gets the total page count. | 
| pageIndex() | Gets the current page index. | 
| pageIndex(newIndex) | Switches the UI component 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 data rows. | 
| refresh(changesOnly) | Reloads data and repaints all or only updated data rows. | 
| repaint() | Renders the component again without reloading data. Use the method to update the component's markup and appearance dynamically. | 
| repaintRows(rowIndexes) | Repaints specific rows. | 
| resetOption(optionName) | Resets a property to its default value. | 
| saveEditData() | Saves changes that a user made to data. | 
| searchByText(text) | Seeks a search string in the columns whose allowSearch property 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 UI component state. | 
| state(state) | Sets the UI component state. | 
| totalCount() | Gets the total row count. | 
| undeleteRow(rowIndex) | Recovers a row deleted in batch editing mode. | 
| updateDimensions() | Updates the UI component's content after resizing. | 
See Also
Events
This section describes events fired by this UI component.
| 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 UI component is rendered and each time the component is repainted. | 
| contextMenuPreparing | Raised before the context menu is rendered. | 
| dataErrorOccurred | Raised when an error occurs in the data source. | 
| disposing | Raised before the UI component is disposed of. | 
| editCanceled | Raised after row changes are discarded. | 
| editCanceling | Raised when the edit operation is canceled, but row changes are not yet discarded. | 
| 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. | 
| exporting | Raised before data is exported. | 
| 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 UI component is initialized. | 
| initNewRow | Raised before a new row is added to the UI component. | 
| keyDown | Raised when the UI component is in focus and a key has been pressed down. | 
| optionChanged | Raised after a UI component property 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. | 
| saved | Raised after row changes are saved. | 
| saving | Raised before pending row changes are saved. | 
| selectionChanged | Raised after selecting a row or clearing its selection. | 
| toolbarPreparing | Raised before the toolbar is created. | 
See Also
Row
A grid row.
You can access grid rows using the getVisibleRows() method and within some event handlers, for example, onCellClick, onCellPrepared, onEditorPreparing.
Types
| Name | Description | 
|---|---|
| AdaptiveDetailRowPreparingEvent | The type of the adaptiveDetailRowPreparing event handler's argument. | 
| CellClickEvent | The type of the cellClick event handler's argument. | 
| CellDblClickEvent | The type of the cellDblClick event handler's argument. | 
| CellHoverChangedEvent | The type of the cellHoverChanged event handler's argument. | 
| CellPreparedEvent | The type of the cellPrepared event handler's argument. | 
| ColumnButtonClickEvent | |
| ContentReadyEvent | The type of the contentReady event handler's argument. | 
| ContextMenuPreparingEvent | The type of the contextMenuPreparing event handler's argument. | 
| DataErrorOccurredEvent | The type of the dataErrorOccurred event handler's argument. | 
| DataGridCommandColumnType | Specifies the command column that this object customizes. | 
| DataGridExportFormat | Specifies the availability and captions of data export buttons. | 
| DataGridPredefinedColumnButton | The name used to identify a built-in button. | 
| DataGridPredefinedToolbarItem | A name used to identify the toolbar item. | 
| DataGridScrollMode | Specifies the scrolling mode. | 
| DisposingEvent | The type of the disposing event handler's argument. | 
| EditCanceledEvent | The type of the editCanceled event handler's argument. | 
| EditCancelingEvent | The type of the editCanceling event handler's argument. | 
| Editing | Configures editing. | 
| EditingStartEvent | The type of the editingStart event handler's argument. | 
| EditorPreparedEvent | The type of the editorPrepared event handler's argument. | 
| EditorPreparingEvent | The type of the editorPreparing event handler's argument. | 
| Export | Configures client-side exporting. | 
| ExportingEvent | The type of the exporting event handler's argument. | 
| ExportTexts | Configures the texts of export commands, buttons, and hints. | 
| FocusedCellChangedEvent | The type of the focusedCellChanged event handler's argument. | 
| FocusedCellChangingEvent | The type of the focusedCellChanging event handler's argument. | 
| FocusedRowChangedEvent | The type of the focusedRowChanged event handler's argument. | 
| FocusedRowChangingEvent | The type of the focusedRowChanging event handler's argument. | 
| GroupData | Specifies a group of elements in a template. | 
| Grouping | Configures grouping. | 
| GroupingTexts | Defines the texts of grouping-related visual elements. | 
| GroupPanel | Configures the group panel. | 
| InitializedEvent | The type of the initialized event handler's argument. | 
| InitNewRowEvent | The type of the initNewRow event handler's argument. | 
| KeyDownEvent | The type of the keyDown event handler's argument. | 
| MasterDetail | Allows you to build a master-detail interface in the grid. | 
| OptionChangedEvent | The type of the optionChanged event handler's argument. | 
| RowClickEvent | The type of the rowClick event handler's argument. | 
| RowCollapsedEvent | The type of the rowCollapsed event handler's argument. | 
| RowCollapsingEvent | The type of the rowCollapsing event handler's argument. | 
| RowDblClickEvent | The type of the rowDblClick event handler's argument. | 
| RowExpandedEvent | The type of the rowExpanded event handler's argument. | 
| RowExpandingEvent | The type of the rowExpanding event handler's argument. | 
| RowInsertedEvent | The type of the rowInserted event handler's argument. | 
| RowInsertingEvent | The type of the rowInserting event handler's argument. | 
| RowPreparedEvent | The type of the rowPrepared event handler's argument. | 
| RowRemovedEvent | The type of the rowRemoved event handler's argument. | 
| RowRemovingEvent | The type of the rowRemoving event handler's argument. | 
| RowUpdatedEvent | The type of the rowUpdated event handler's argument. | 
| RowUpdatingEvent | The type of the rowUpdating event handler's argument. | 
| RowValidatingEvent | The type of the rowValidating event handler's argument. | 
| SavedEvent | The type of the saved event handler's argument. | 
| SavingEvent | The type of the saving event handler's argument. | 
| Scrolling | Configures scrolling. | 
| SelectionChangedEvent | The type of the selectionChanged event handler's argument. | 
| SelectionSensitivity | Specifies sensitivity modes. | 
| SortByGroupSummaryInfoItem | Allows you to sort groups according to the values of group summary items. | 
| Summary | Specifies the properties of the grid summary. | 
| SummaryGroupItem | Specifies items of the group summary. | 
| SummaryTexts | Contains properties that specify text patterns for summary items. | 
| SummaryTotalItem | Specifies items of the total summary. | 
| ToolbarPreparingEvent | The type of the toolbarPreparing event handler's argument. | 
If you have technical questions, please create a support ticket in the DevExpress Support Center.