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 interactive configuration
Copy Code
Copy to Codepen
$("#datagrid").dxDataGrid({
});

                    

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

jQuery
JavaScript
HTML
$(function () {
    $("#dataGrid").dxDataGrid({
        dataSource: customers,
        columns: ['CompanyName', 'City', 'State', 'Phone', 'Fax']
    });
});
<div id="dataGrid"></div>
Angular
HTML
TypeScript
<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 Controls
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

View Demo Watch Video

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.

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.

customizeColumns

Specifies a function that customizes grid columns after they are created.

customizeExportData

Customizes grid columns and data before exporting.

dataSource

Specifies the origin of data for the widget.

dateSerializationFormat

Specifies date-time values' serialization format. 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 export.

filterRow

Configures the filter row.

focusStateEnabled

Specifies whether the widget can be focused using keyboard navigation.

grouping

Specifies grouping settings and the behavior of grouped grid records.

groupPanel

Configures the group panel.

headerFilter

Configures the header filter feature.

height

Specifies the widget's height.

hint

Specifies text for a hint that appears when a user pauses on the widget.

hoverStateEnabled

Specifies whether grid rows are highlighted when the mouse pointer moves over them.

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 handler for the adaptiveDetailRowPreparing event. Executed before an adaptive detail row is rendered.

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 dataErrorOccurred event. Executed when an error occurs in the data source.

onDisposing

A handler for the disposing event. Executed when the widget is removed from the DOM using the remove(), empty(), or html() jQuery methods only.

onEditingStart

A handler for the editingStart event. Executed before a cell or row switches to the editing state.

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. Executed before a new row is added to the widget.

onKeyDown

A handler for the keyDown event. Executed when the widget is in focus and a key has been pressed down.

onOptionChanged

A handler for the optionChanged event. Executed after an option of the widget is changed.

onRowClick

A handler for the rowClick event.

onRowCollapsed

A handler for the rowCollapsed event. Executed after a row is collapsed.

onRowCollapsing

A handler for the rowCollapsing event. Executed before a row is collapsed.

onRowExpanded

A handler for the rowExpanded event. Executed after a row is expanded.

onRowExpanding

A handler for the rowExpanding event. Executed before a row is expanded.

onRowInserted

A handler for the rowInserted event. Executed after a new row has been inserted into the data source.

onRowInserting

A handler for the rowInserting event. Executed before a new row is inserted into the data source.

onRowPrepared

A handler for the rowPrepared event.

onRowRemoved

A handler for the rowRemoved event. Executed after a row has been removed from the data source.

onRowRemoving

A handler for the rowRemoving event. Executed before a row is removed from the data source.

onRowUpdated

A handler for the rowUpdated event. Executed after a row has been updated in the data source.

onRowUpdating

A handler for the rowUpdating event. Executed before a row is updated in the data source.

onRowValidating

A handler for the rowValidating event. Executed after cells in a row are validated against validation rules.

onSelectionChanged

A handler for the selectionChanged event. Executed after selecting a row or clearing its selection.

onToolbarPreparing

A handler for the toolbarPreparing event. Executed before the toolbar is created.

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 rows should be shaded differently.

rowTemplate

Specifies a custom template for grid rows.

rtlEnabled

Switches the widget to a right-to-left representation.

scrolling

Configures scrolling.

searchPanel

Configures the search panel.

selectedRowKeys

Specifies the keys of rows that must be selected initially. 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.

Methods

This section describes the methods that can be used to manipulate the DataGrid widget.

Name Description
addColumn(columnOptions)

Adds a new column to the widget.

addRow()

Adds an empty data row.

beginCustomLoading(messageText)

Displays the load panel.

beginUpdate()

Prevents the widget from refreshing until the endUpdate() method is called.

byKey(key)

Allows you to obtain a data object by its key.

cancelEditData()

Discards changes that a user made to data.

cellValue(rowIndex, dataField)

Gets the value of a cell found by the row index and data field.

cellValue(rowIndex, dataField, value)

Assigns a new value to a cell found by the row index and data field.

cellValue(rowIndex, visibleColumnIndex)

Gets the value of a cell found by the row index and column index.

cellValue(rowIndex, visibleColumnIndex, value)

Assigns a new value to a cell found by the row index and column index.

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 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 the widget including visible and hidden columns, but without command columns.

columnOption(id)

Gets the options of a column using its identifier.

columnOption(id, optionName)

Gets the value of a specific option set for a specific column.

columnOption(id, optionName, optionValue)

Assigns a new value to a single option of a specific column.

columnOption(id, options)

Assigns new values to several options of a specific column at once.

defaultOptions(rule)

Specifies the device-dependent default configuration options for this component.

deleteColumn(id)

Removes a specific column from the widget.

deleteRow(rowIndex)

Removes a specific row from the widget.

deselectAll()

Clears the selection of all rows on all pages or the currently rendered page only.

deselectRows(keys)

Clears selection of specific rows.

editCell(rowIndex, dataField)

Switches a specific cell into the editing state. The cell is found by the row index and data field. Takes effect only if the editing mode is 'batch' or 'cell'.

editCell(rowIndex, visibleColumnIndex)

Switches a specific cell into the editing state. The cell is found by the row index and column index. Takes effect only if the editing mode is 'batch' or 'cell'.

editRow(rowIndex)

Switches a specific row into the editing state. Takes effect only if the editing mode is 'row', 'popup' or 'form'.

element()

Gets the root element of the widget.

endCustomLoading()

Hides the load panel.

endUpdate()

Refreshes the widget after a call of the beginUpdate() method.

expandAdaptiveDetailRow(key)

Expands an adaptive detail row found 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 widget's data source using the filter(filterExpr) method.

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 by the row index and data field.

getCellElement(rowIndex, visibleColumnIndex)

Gets a cell by the row index and column index.

getCombinedFilter()

Returns the total filter that combines all the filters applied.

getCombinedFilter(returnDataField)

Returns the total filter that combines all the filters applied.

getDataSource()

Gets the DataSource instance.

getKeyByRowIndex(rowIndex)

Gets the key of a row by its index.

getRowElement(rowIndex)

Gets the element of a row by its index.

getRowIndexByKey(key)

Gets the index of a row by its key.

getScrollable()

Gets the instance of the scrollable part of the widget.

getSelectedRowKeys()

Gets the keys of the currently selected rows.

getSelectedRowsData()

Gets data objects of currently selected rows.

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()

Returns this widget's instance. Use it to access other methods of the widget.

isAdaptiveDetailRowExpanded(key)

Checks whether a specific adaptive detail row is expanded or collapsed.

isRowExpanded(key)

Checks whether a specific group or master row is expanded or collapsed.

isRowSelected(data)

Checks whether the row that represents a specific data object is selected. Takes effect only if selection.deferred is true.

isRowSelected(key)

Checks whether the row with a specific key is selected. Takes effect only if selection.deferred is false.

keyOf(obj)

Gets a data object's key.

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()

Gets the widget's options.

option(optionName)

Gets a specific option value.

option(optionName, optionValue)

Assigns a new value to a specific option.

option(options)

Sets one or more options.

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()

Reloads data in the widget.

repaint()

Repaints the widget. Call it if you made modifications that changed the widget's state to invalid.

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 by keys.

selectRowsByIndexes(indexes)

Selects rows by indexes.

showColumnChooser()

Shows the column chooser.

state()

Gets the current DataGrid state.

state(state)

Sets the DataGrid state.

totalCount()

Returns the number of records currently held by a grid.

undeleteRow(rowIndex)

Recovers a row deleted in batch editing mode.

updateDimensions()

Updates the widget's content after resizing.

Events

This section describes events fired by this widget.

Name Description
adaptiveDetailRowPreparing

Raised before an adaptive detail row is 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

Raised when an error occurs in the data source.

disposing

Raised when the widget is removed from the DOM using the remove(), empty(), or html() jQuery methods only.

editingStart

Raised before a cell or row switches to 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

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 an option of the widget is changed.

rowClick

Fires when a user clicks a grid row.

rowCollapsed

Raised after a row is collapsed.

rowCollapsing

Raised before a row is collapsed.

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

Fires after a row has been rendered.

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

This section describes the properties of a grid row. An object containing these properties comes to certain event-handling functions.

Type:

Object