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.

Included in: dx.web.js, dx.viz-web.js, dx.all.js

Module: ui/data_grid

Export: default

$("#datagrid").dxDataGrid({

});

You can create the widget using one of the following approaches.

jQuery

HTML

JavaScript

<div id="dataGrid"></div>

$(function () {
    $("#dataGrid").dxDataGrid({
        dataSource: customers,
        columns: ['CompanyName', 'City', 'State', 'Phone', 'Fax']
    });
});

Angular

HTML

JavaScript

<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 = [
        // ...   
    ];
}

AngularJS

HTML

JavaScript

<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 = [
            // ...   
        ];
    });

Knockout

HTML

JavaScript

<div data-bind="dxDataGrid: {
    dataSource: customers,
    columns: ['CompanyName', 'City', 'State', 'Phone', 'Fax']
}"></div>

var viewModel = {
    customers: [
        // ...
    ]
};
ko.applyBindings(viewModel);

ASP.NET MVC Wrappers

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.

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.

DataGrid

See Also

Configuration

Methods

Events

See Also

Row