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

    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.

See Also

View Demo Watch Video

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.