DataGrid
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.
You can create the widget using one of the following approaches.
-
HTMLJavaScript
<div id="dataGrid"></div>
$(function () { $("#dataGrid").dxDataGrid({ dataSource: customers, columns: ['CompanyName', 'City', 'State', 'Phone', 'Fax'] }); });
-
HTMLJavaScript
<dx-data-grid [dataSource]="customers"> <dxi-column dataField="CompanyName"></dxi-column> <dxi-column dataField="City"></dxi-column> <dxi-column dataField="State"></dxi-column> <dxi-column dataField="Phone"></dxi-column> <dxi-column dataField="Fax"></dxi-column> </dx-data-grid>
export class AppComponent { customers = [ // ... ]; }
-
HTMLJavaScript
<div ng-controller="DemoController"> <div dx-data-grid="{ dataSource: customers, columns: ['CompanyName', 'City', 'State', 'Phone', 'Fax'] }"></div> </div>
angular.module('DemoApp', ['dx']) .controller("DemoController", function ($scope) { $scope.customers = [ // ... ]; });
-
HTMLJavaScript
<div data-bind="dxDataGrid: { dataSource: customers, columns: ['CompanyName', 'City', 'State', 'Phone', 'Fax'] }"></div>
var viewModel = { customers: [ // ... ] }; ko.applyBindings(viewModel);
-
Razor C#Razor VB
@(Html.DevExtreme().DataGrid() .ID("dataGrid") .DataSource(Customers) .Columns(columns => { columns.Add().DataField("CompanyName"); columns.Add().DataField("City"); columns.Add().DataField("State"); columns.Add().DataField("Phone"); columns.Add().DataField("Fax"); }) )
@(Html.DevExtreme().DataGrid() _ .ID("dataGrid") _ .DataSource(Customers) _ .Columns(Sub(columns) columns.Add().DataField("CompanyName") columns.Add().DataField("City") columns.Add().DataField("State") columns.Add().DataField("Phone") columns.Add().DataField("Fax") End Sub) )
Note that DevExtreme widgets require you to link the jQuery library to your application. If you use the Knockout or AngularJS approach, the Knockout or AngularJS library is also required. For detailed information on linking these libraries to your project, refer to the topics in the Installation section.
See Also
Configuration
This section describes the configuration options of the DataGrid widget.
Name | Description |
---|---|
accessKey | Specifies a shortcut key that sets focus on the widget element. |
activeStateEnabled | A Boolean value specifying whether or not the widget changes its state when interacting with a user. |
allowColumnReordering | Specifies whether or not grid columns can be reordered by a user. |
allowColumnResizing | Specifies whether or not grid columns can be resized by a user. |
cacheEnabled | Specifies whether or not to enable data caching. |
cellHintEnabled | Enables a hint that appears when a user hovers the mouse pointer over a cell with truncated content. |
columnAutoWidth | Specifies whether or not the width of grid columns depends on column content. |
columnChooser | Specifies the options of a column chooser. |
columnFixing | Specifies options for column fixing. |
columnHidingEnabled | Specifies whether the widget should hide columns in order to adapt to the screen or container size. |
columns | An array of grid columns. |
customizeColumns | Specifies a function that customizes grid columns after they are created. |
customizeExportData | Customizes grid columns and data before exporting. |
dataSource | Specifies a data source for the grid. |
dateSerializationFormat | Specifies the serialization format for date-time values. |
disabled | A Boolean value specifying whether or not the widget can respond to user interaction. |
editing | Contains options that specify how grid content can be changed. |
elementAttr | Specifies the attributes to be attached to the widget's root element. |
errorRowEnabled | Indicates whether to show the error row for the grid. |
export | Configures client-side export. |
filterRow | Specifies filter row options. |
focusStateEnabled | Specifies whether or not the widget can be focused. |
grouping | Specifies grouping settings and the behavior of grouped grid records. |
groupPanel | Configures the group panel. |
headerFilter | Specifies options for filtering using a column header filter. |
height | Specifies the height of the widget. |
hint | Specifies the text of the hint displayed for the widget. |
hoverStateEnabled | Specifies whether grid rows are highlighted when the mouse pointer moves over them. |
loadPanel | Specifies options configuring the load panel. |
masterDetail | Allows you to build a master-detail interface in the grid. |
noDataText | Specifies text displayed when a grid does not contain any records. |
onAdaptiveDetailRowPreparing | A handler for the adaptiveDetailRowPreparing event. |
onCellClick | A handler for the cellClick event. |
onCellHoverChanged | A handler for the cellHoverChanged event. |
onCellPrepared | A handler for the cellPrepared event. |
onContentReady | A handler for the contentReady event. Executed when the widget's content is ready. This handler may be executed multiple times during the widget's lifetime depending on the number of times its content changes. |
onContextMenuPreparing | A handler for the contextMenuPreparing event. |
onDataErrorOccurred | A handler for the dataErrorOccured event. |
onDisposing | A handler for the disposing event. |
onEditingStart | A handler for the editingStart event. |
onEditorPrepared | A handler for the editorPrepared event. |
onEditorPreparing | A handler for the editorPreparing event. |
onExported | A handler for the exported event. |
onExporting | A handler for the exporting event. |
onFileSaving | A handler for the fileSaving event. |
onInitialized | A handler for the initialized event. Executed only once, after the widget is initialized. |
onInitNewRow | A handler for the initNewRow event. |
onKeyDown | A handler for the keyDown event. |
onOptionChanged | A handler for the optionChanged event. |
onRowClick | A handler for the rowClick event. |
onRowCollapsed | A handler for the rowCollapsed event. |
onRowCollapsing | A handler for the rowCollapsing event. |
onRowExpanded | A handler for the rowExpanded event. |
onRowExpanding | A handler for the rowExpanding event. |
onRowInserted | A handler for the rowInserted event. |
onRowInserting | A handler for the rowInserting event. |
onRowPrepared | A handler for the rowPrepared event. |
onRowRemoved | A handler for the rowRemoved event. |
onRowRemoving | A handler for the rowRemoving event. |
onRowUpdated | A handler for the rowUpdated event. |
onRowUpdating | A handler for the rowUpdating event. |
onRowValidating | A handler for the rowValidating event. |
onSelectionChanged | A handler for the selectionChanged event. |
onToolbarPreparing | A handler for the toolbarPreparing event. |
pager | Specifies the options of a grid pager. |
paging | Specifies paging options. |
remoteOperations | Specifies the operations that must be performed on the server side. |
rowAlternationEnabled | Specifies whether or not grid rows must be shaded in a different way. |
rowTemplate | Specifies a custom template for grid rows. |
rtlEnabled | Specifies whether or not the current component supports a right-to-left representation. |
scrolling | A configuration object specifying scrolling options. |
searchPanel | Specifies options of the search panel. |
selectedRowKeys | Specifies the keys of the records that must appear initially selected. |
selection | Specifies options of runtime selection. |
selectionFilter | Specifies filters for the records that must appear initially selected. |
showBorders | Specifies whether the outer borders of the grid are visible or not. |
showColumnHeaders | Specifies whether column headers are visible or not. |
showColumnLines | Specifies whether or not vertical lines separating one grid column from another are visible. |
showRowLines | Specifies whether or not horizontal lines separating one grid row from another are visible. |
sortByGroupSummaryInfo | Allows you to sort groups according to the values of group summary items. |
sorting | Specifies options of runtime sorting. |
stateStoring | Specifies options of state storing. |
summary | Specifies the options of the grid summary. |
tabIndex | Specifies the widget tab index. |
twoWayBindingEnabled | Specifies whether to enable two-way data binding. |
visible | A Boolean value specifying whether or not the widget is visible. |
width | Specifies the width of the widget. |
wordWrapEnabled | Specifies whether text that does not fit into a column should be wrapped. |
Methods
This section describes the methods that can be used to manipulate the DataGrid widget.
Name | Description |
---|---|
addColumn(columnOptions) | Adds a new column to a grid. |
addRow() | Adds a new data row to a grid. |
beginCustomLoading(messageText) | Displays the load panel. |
beginUpdate() | Prevents the component from refreshing until the endUpdate() method is called. |
byKey(key) | Allows you to obtain a data object by its key. |
cancelEditData() | Discards changes made in a grid. |
cellValue(rowIndex, dataField) | Gets the cell value. |
cellValue(rowIndex, dataField, value) | Sets the cell value. |
cellValue(rowIndex, visibleColumnIndex) | Gets the cell value. |
cellValue(rowIndex, visibleColumnIndex, value) | Sets the cell value. |
clearFilter() | Clears all filters applied to grid rows. |
clearFilter(filterName) | Clears all filters of a specific type applied to grid rows. |
clearGrouping() | Ungroups grid records. |
clearSelection() | Clears selection of all grid rows on all pages. |
clearSorting() | Clears sorting settings of all grid columns at once. |
closeEditCell() | Draws the cell being edited from the editing state. Use this method when the edit mode is batch. |
collapseAdaptiveDetailRow() | Collapses the currently expanded adaptive detail row (if there is one). |
collapseAll(groupIndex) | Collapses groups or master rows in a grid. |
collapseRow(key) | Allows you to collapse a specific group or master row by its key. |
columnCount() | Returns the number of data columns in a grid. |
columnOption(id) | Returns the options of a column by an identifier. |
columnOption(id, optionName) | Returns the value of a specific column option. |
columnOption(id, optionName, optionValue) | Sets an option of a specific column. |
columnOption(id, options) | Sets several options of a column at once. |
defaultOptions(rule) | Specifies the device-dependent default configuration options for this component. |
deleteColumn(id) | Removes the column from the grid. |
deleteRow(rowIndex) | Removes a specific row from a grid. |
deselectAll() | Clears selection of all grid rows on the current page only or on all pages. |
deselectRows(keys) | Clears selection of specified grid rows. |
editCell(rowIndex, dataField) | Sets a specific cell into the editing state. |
editCell(rowIndex, visibleColumnIndex) | Sets a specific cell into the editing state. |
editRow(rowIndex) | Sets a specific row into the editing state. |
element() | Returns the root HTML element of the widget. |
endCustomLoading() | Hides the load panel. |
endUpdate() | Enables the component to refresh after the beginUpdate() method call. |
expandAdaptiveDetailRow(key) | Expands an adaptive detail row by the key of its parent data row. |
expandAll(groupIndex) | Expands groups or master rows in a grid. |
expandRow(key) | Allows you to expand a specific group or master row by its key. |
exportToExcel(selectionOnly) | Exports grid data to Excel. |
filter() | Returns a filter expression applied to the grid's data source using the filter(filterExpr) method. |
filter(filterExpr) | Applies a filter to the grid's data source. |
focus() | Sets focus on the widget. |
focus(element) | Focuses the specified cell element in the grid. |
getCellElement(rowIndex, dataField) | Allows you to obtain a cell by its row index and the data field of its column. |
getCellElement(rowIndex, visibleColumnIndex) | Allows you to obtain a cell by its row index and the visible index of its column. |
getCombinedFilter() | Returns a filter expression applied to the grid using all possible scenarios. |
getCombinedFilter(returnDataField) | Returns a filter expression applied to the grid using all possible scenarios. |
getDataSource() | Allows you to get the DataSource instance. |
getKeyByRowIndex(rowIndex) | Allows you to obtain the data key by a row index. |
getRowElement(rowIndex) | Allows you to obtain a row element by its index. |
getRowIndexByKey(key) | Allows you to obtain the row index by a data key. |
getScrollable() | Gets an instance of the scrollable part of the DataGrid widget. |
getSelectedRowKeys() | Gets the keys of currently selected grid records. |
getSelectedRowsData() | Gets data objects of currently selected rows. |
getTotalSummaryValue(summaryItemName) | Gets the value of a total summary item. |
getVisibleColumns() | Gets an array of visible columns. |
getVisibleColumns(headerLevel) | Gets an array of visible columns at a specific hierarchical level of column headers. |
getVisibleRows() | Gets an array of visible rows. |
hasEditData() | Checks whether or not the grid contains unsaved changes. |
hideColumnChooser() | Hides the column chooser panel. |
instance() | Returns an instance of this component class. |
isAdaptiveDetailRowExpanded(key) | Checks whether a specific adaptive detail row is expanded or collapsed. |
isRowExpanded(key) | Allows you to find out whether a specific group or master row is expanded or collapsed. |
isRowSelected(data) | Allows you to find out whether or not the row with a specified data object is selected. |
isRowSelected(key) | Allows you to find out whether or not the row with a specified key is selected. |
keyOf(obj) | Returns the key corresponding to the passed data object. |
off(eventName) | Detaches all event handlers from the specified event. |
off(eventName, eventHandler) | Detaches a particular event handler from the specified event. |
on(eventName, eventHandler) | Subscribes to a specified event. |
on(events) | Subscribes to the specified events. |
option() | Returns the configuration options of this component. |
option(optionName) | Gets the value of the specified configuration option of this component. |
option(optionName, optionValue) | Sets a value to the specified configuration option of this component. |
option(options) | Sets one or more options of this component. |
pageCount() | Returns how many pages the grid contains. |
pageIndex() | Gets the index of the current page. |
pageIndex(newIndex) | Switches a grid to a specified page. |
pageSize() | Gets the current page size. |
pageSize(value) | Sets the page size. |
refresh() | Refreshes grid data. |
repaint() | Redraws the widget. |
repaintRows(rowIndexes) | Redraws the specified rows. |
saveEditData() | Saves changes made in a grid. |
searchByText(text) | Searches grid records by a search string. |
selectAll() | Selects all rows. |
selectRows(keys, preserve) | Selects specified grid rows. |
selectRowsByIndexes(indexes) | Selects grid rows by indexes. |
showColumnChooser() | Invokes the column chooser panel. |
state() | Returns the current state of the grid. |
state(state) | Sets the grid state. |
totalCount() | Returns the number of records currently held by a grid. |
undeleteRow(rowIndex) | Recovers a row deleted in the batch edit mode. |
updateDimensions() | Updates the grid to the size of its content. |
Events
This section describes events fired by this widget.
Name | Description |
---|---|
adaptiveDetailRowPreparing | Fires before an adaptive detail row will be rendered. |
cellClick | Fires when a user clicks a grid cell. |
cellHoverChanged | Fires when the hover state of a cell is changed. |
cellPrepared | Fires after a cell has been rendered. |
contentReady | Raised when the widget's content is ready. |
contextMenuPreparing | Fires before displaying a context menu that is invoked on one of the grid's header or row cells. |
dataErrorOccurred | Fires when an error occurs in the data source. |
disposing | Fires when the widget is being removed. |
editingStart | Fires before a row (in row edit mode) or a cell (in batch edit mode) switches into the editing state. |
editorPrepared | Fires after an editor is created. |
editorPreparing | Fires before an editor is created. |
exported | Fires after the exporting of grid data is completed. |
exporting | Fires before exporting grid's data. |
fileSaving | Fires before the grid saves an Excel file with exported data on the user's local storage. |
initialized | Raised only once, after the widget is initialized. |
initNewRow | Fires on row insertion. |
keyDown | Fires when a key is pressed down when the widget is focused. |
optionChanged | Fires after an option of the component is changed. |
rowClick | Fires when a user clicks a grid row. |
rowCollapsed | Fires after a master or group row is collapsed in the grid. |
rowCollapsing | Fires before a master or group row is collapsed in the grid. |
rowExpanded | Fires after a master or group row is expanded in the grid. |
rowExpanding | Fires before a master or group row is expanded in the grid. |
rowInserted | Fires after a row has been inserted into the data source. |
rowInserting | Fires before a grid row is transmitted to the data source. |
rowPrepared | Fires after a row has been rendered. |
rowRemoved | Fires after a row has been removed from the data source. |
rowRemoving | Fires before a row is removed from a data source. |
rowUpdated | Fires after a row has been updated in the data source. |
rowUpdating | Fires before a row is updated in a data source. |
rowValidating | Fires when a cell(s) in a row is validated. |
selectionChanged | Fires when a grid record has been selected/deselected. |
toolbarPreparing | Fires before the toolbar is created. |
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.
We appreciate your feedback.