Configuration

This section describes the configuration options of the DataGrid widget.

accessKey

Specifies the shortcut key that sets focus on the widget.

Type: String
Default Value: null

The value of this option will be passed to the accesskey attribute of the HTML element that underlies the widget.

activeStateEnabled

Specifies whether or not the widget changes its state when interacting with a user.

Type: Boolean
Default Value: false

This option is used when the widget is displayed on a platform whose guidelines include the active state change for widgets.

allowColumnReordering

Specifies whether a user can reorder columns.

Type: Boolean
Default Value: false

Initially, columns appear in the order specified by the columns array. If you skip specifying this array, columns will mirror the order of fields in the first object from the dataSource. You can allow a user to reorder columns at runtime by setting the allowColumnReordering option to true.

See Also
Show Example:
AngularJS
Knockout
jQuery

Toggle the check box below to change the value of the allowColumnReordering option. Then, try to reorder grid columns by dragging a column by its header and dropping it at the required place.


                                    

                                    

Toggle the check box below to change the value of the allowColumnReordering option. Then, try to reorder grid columns by dragging a column by its header and dropping it at the required place.


                                    

                                    

Toggle the check box below to change the value of the allowColumnReordering option. Then, try to reorder grid columns by dragging a column by its header and dropping it at the required place.


                                    

                                    

allowColumnResizing

Specifies whether a user can resize columns.

Type: Boolean
Default Value: false

By default, the width of each column depends on the width of the widget and the total number of columns. You can allow a user to resize the columns at runtime by setting the allowColumnResizing option to true.

See Also
Show Example:
AngularJS
Knockout
jQuery

Toggle the check box below to change the value of the allowColumnResizing option. Then, try to resize a grid column by dragging its border.


                                    

                                    

Toggle the check box below to change the value of the allowColumnResizing option. Then, try to resize a grid column by dragging its border.


                                    

                                    

Toggle the check box below to change the value of the allowColumnResizing option. Then, try to resize a grid column by dragging its border.


                                    

                                    

cacheEnabled

Specifies whether data should be cached.

Type: Boolean
Default Value: true

When this option is set to true, data loaded once is saved in cache. Then, the widget takes data from this cache when performing such operations as sorting, grouping, paging, etc. Caching is helpful when the data source takes significant time to load. But, consider disabling it for frequently changing data sources.

To update data in cache, call the refresh() method of the widget or the load() method of the DataSource.

NOTE
If you fetch data from the server, some operations with data can be executed remotely, while others - locally. If you perform basic operations (sorting, filtering, and paging) remotely and advanced operations (grouping and summary calculation) locally, certain user actions will force DataGrid to query the server for data repeatedly despite caching being enabled. Particularly, the advanced operations demand data to be reloaded completely from the server to provide correct results.
See Also

cellHintEnabled

Enables a hint that appears when a user hovers the mouse pointer over a cell with truncated content.

Type: Boolean
Default Value: true

The cell's content may be truncated if the width of the cell's column becomes very small. In this case, when a user hovers the mouse pointer over such a cell, a hint containing the cell's value appears. To disable cell hints, assign false to the cellHintEnabled option.

columnAutoWidth

Specifies whether columns should adjust their widths to the content.

Type: Boolean
Default Value: false

When this option is set to true, all columns adjust their widths to the content. This setting may cause horizontal scrolling, but only if the overall content is longer than the width of the widget. In this case, you can fix those columns that you consider pivotal so that they were constantly on screen.

When this option is set to false, all columns have identical widths that depend on the width of the widget.

See Also
Show Example:
AngularJS
Knockout
jQuery

In this example, you can change the value of the columnAutoWidth option using the check box below. Note that when this option is true, each grid column has a width that is optimal for displaying the content of this column in full. However, with this setting applied, horizontal scrolling appears as well. When the aforementioned option is false, grid columns have an even width.


                                    

                                    

In this example, you can change the value of the columnAutoWidth option using the check box below. Note that when this option is true, each grid column has a width that is optimal for displaying the content of this column in full. However, with this setting applied, horizontal scrolling appears as well. When the aforementioned option is false, grid columns have an even width.


                                    

                                    

In this example, you can change the value of the columnAutoWidth option using the check box below. Note that when this option is true, each grid column has a width that is optimal for displaying the content of this column in full. However, with this setting applied, horizontal scrolling appears as well. When the aforementioned option is false, grid columns have an even width.


                                    

                                    

columnChooser

Configures the column chooser.

Type: Object

The column chooser allows a user to hide columns at runtime. To enable it, assign true to the columnChooser.enabled option.

DevExtreme HTML5 JavaScript jQuery Angular Knockout Widget DataGrid ColumnChooser

See Also
Show Example:
AngularJS
Knockout
jQuery

In this example, you can show/hide grid columns using the column chooser. To invoke it, click the column chooser icon. Drag a column by its header onto/from the column chooser to hide/show this column. Additionally, several options that define the column chooser appearance are changed.


                                    

                                    

In this example, you can show/hide grid columns using the column chooser. To invoke it, click the column chooser icon. Drag a column by its header onto/from the column chooser to hide/show this column. Additionally, several options that define the column chooser appearance are changed.


                                    

                                    

In this example, you can show/hide grid columns using the column chooser. To invoke it, click the column chooser icon. Drag a column by its header onto/from the column chooser to hide/show this column. Additionally, several options that define the column chooser appearance are changed.


                                    

                                    

columnFixing

Configures column fixing.

Type: Object

When the width of all columns exceeds the widget width, horizontal scrolling appears. If specific columns should be on screen constantly regardless of how far the widget is scrolled, allow a user to fix them at runtime using the context menu. For this, set the columnFixing.enabled option to true.

DevExtreme HTML5 JavaScript jQuery Angular Knockout Widget DataGrid ColumnFixing

When you enable column fixing, command columns become fixed automatically.

View Demo

See Also

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".

Type: Boolean
Default Value: false

When displaying the widget in your app, you may want to use different layouts for different screen sizes. While desktop monitors provide enough space to display all columns, mobile screens do not. You can enable the widget to hide certain columns automatically if they do not fit into the screen size by assigning true to the columnHidingEnabled option. Information from hidden columns is available in the adaptive detail row.

When hiding columns, the widget uses the following principles:

  1. The lower the hidingPriority, the higher the probability that the widget hides this column. When you do not specify hiding priorities, their values ascend from right to left beginning with 0. This means that the widget hides the rightmost columns at first.
  2. If the width of a column is specified, this column is hidden only if it exceeds the width of the widget.
  3. If the width of a column is not specified, this column is hidden only if its content overflows it.
See Also

columnMinWidth

Specifies the minimum width of columns.

Type: Number
Default Value: undefined

columnResizingMode

Specifies how the widget resizes columns. Applies only if allowColumnResizing is true.

Type: String
Default Value: 'nextColumn'
Accepted Values: 'nextColumn' | 'widget'

The columnResizingMode option accepts one of the following values.

  • nextColumn
    When a user resizes a column, the width of the next column changes.
  • widget
    When a user resizes a column, the width of the widget changes.

columns[]

An array of grid columns.

Type: Array
Default Value: undefined

By default, a column is created for each field of a data source object, but in most cases, it is redundant. To specify a set of columns to be created in a grid, assign an array specifying these columns to the columns option. Each grid column is represented in this array by an object containing column settings or by a data source field that this column is bound to. Detailed information on specifying grid columns is given in the Columns Overview article.

Column options define the behavior and appearance of a grid column. One of the other capabilities allows you to control the sorting of column values using the allowSorting and sortOrder options, apply a filter to grid records using the allowFiltering and filterOperations options, and group grid records using the allowGrouping and groupIndex options. In addition, you can change the visibility and width of a column using corresponding options.

To get or set an option or several options for a column at runtime, use the columnOption method with the required arguments.

View Demo Watch Video

See Also

customizeColumns

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

Type: function
Function parameters:
columns: Array

Grid columns.

Usually, each column in DataGrid is configured individually using options within the objects of the columns array. In most cases, configuring grid columns in this fashion is sufficient to make them appear appropriately. However, there may be scenarios when columns are generated on the base of a data source and you need to adjust a few of their options. In that case, you do not need to declare the columns array. Instead, change the required options within a callback function assigned to the customizeColumns option. An array of grid columns can be accessed using the function parameter. Fields of each object in this array represent column options identical to the options described in the columns reference section.

Show Example:
AngularJS
Knockout
jQuery

In this example, grid columns are created automatically on the base of the data source. Further, the widths of the "Author" and "Title" columns are adjusted using a callback function assigned to the customizeColumns option.


                                    

                                    

In this example, grid columns are created automatically on the base of the data source. Further, the widths of the "Author" and "Title" columns are adjusted using a callback function assigned to the customizeColumns option.


                                    

                                    

In this example, grid columns are created automatically on the base of the data source. Further, the widths of the "Author" and "Title" columns are adjusted using a callback function assigned to the customizeColumns option.


                                    

                                    

customizeExportData

Customizes grid columns and data before exporting.

Type: function
Function parameters:
columns: Array
rows: Array

Grid rows. If only selected rows are to be exported, this array contains only them.

The function assigned to this option will be called between the onExporting and onExported functions. Use the arguments of this function to access and change different column and row options.

See Also

dataSource

Specifies the origin of data for the widget.

Default Value: null

This option accepts one of the following.

  • Array of Objects
    A simple JavaScript array containing a collection of plain objects.

  • URL
    A URL to JSON data or to a service returning data in JSON format.

  • DataSource or its configuration object
    A DataSource is an object that provides a handy API for data processing. A DataSource is a stateful object, which means that it saves data processing settings and applies them each time data is loaded. All underlying data access logic of a DataSource is isolated in a Store. A Store provides an API for reading and modifying data. Unlike the DataSource, a Store is a stateless object.

    NOTE
    If you use data mapping, features like export and selection may work incorrectly. We recommend using calculated columns instead of mapping.

The widget cannot track changes that a third party makes in the data source. To bring data in the widget up to date in this case, call the refresh() method.

See Also
Show Example:
AngularJS
Knockout
jQuery

In this example, the data source is declared as an array of objects that each contain the 'author', 'title', 'year', 'genre' and 'format' fields. The corresponding columns are generated automatically. Captions for column headers are generated based on the data field names.


                                    

                                    

In this example, the data source is declared as an array of objects that each contain the 'author', 'title', 'year', 'genre' and 'format' fields. The corresponding columns are generated automatically. Captions for column headers are generated based on the data field names.


                                    

                                    

In this example, the data source is declared as an array of objects that each contain the 'author', 'title', 'year', 'genre' and 'format' fields. The corresponding columns are generated automatically. Captions for column headers are generated based on the data field names.


                                    

                                    

dateSerializationFormat

Specifies the serialization format for date-time values.

Type: String

If you do not set the dataSource option at design time, the widget cannot detect the format of date-time values automatically. In this case, specify the dateSerializationFormat option. You can also do this to serialize date-time values to a specific format.

The following formats are supported.

  • "yyyy-MM-dd" - a local date

  • "yyyy-MM-ddTHH:mm:ss" - a local date and time

  • "yyyy-MM-ddTHH:mm:ssZ" - a UTC date and time

  • "yyyy-MM-ddTHH:mm:ssx" - a date and time with a timezone

Note that this option only applies if the forceIsoDateParsing field of the global configuration object is set to true.

disabled

Specifies whether the widget responds to user interaction.

Type: Boolean
Default Value: false

Show Example:
AngularJS
Knockout
jQuery

In this example, you can enable/disable the DataGrid widget by toggling the check box below. When the widget is enabled, you can interact with it, for example, apply sorting or switch between pages. When the widget is disabled, it does not respond to your actions.


                                    

                                    

In this example, you can enable/disable the DataGrid widget by toggling the check box below. When the widget is enabled, you can interact with it, for example, apply sorting or switch between pages. When the widget is disabled, it does not respond to your actions.


                                    

                                    

In this example, you can enable/disable the DataGrid widget by toggling the check box below. When the widget is enabled, you can interact with it, for example, apply sorting or switch between pages. When the widget is disabled, it does not respond to your actions.


                                    

                                    

editing

Configures editing.

Type: Object

The widget can allow a user to add, update and delete data. To control which of these operations are allowed, use the allowAdding, allowUpdating and allowDeleting options. Editing can be carried out in different modes, which are detailed in the mode option's description.

NOTE
Before allowing a user to add, update, and delete, make sure that your data source supports these actions.

View Demo

See Also
Show Example:
AngularJS
Knockout
jQuery

In this example, you can perform all kinds of data modifications available in the DataGrid widget: row editing, insertion and removal. These operations are conducted in the batch edit mode. All these settings are specified using the fields of the editing configuration object.


                                    

                                    

In this example, you can perform all kinds of data modifications available in the DataGrid widget: row editing, insertion and removal. These operations are conducted in the batch edit mode. All these settings are specified using the fields of the editing configuration object.


                                    

                                    

In this example, you can perform all kinds of data modifications available in the DataGrid widget: row editing, insertion and removal. These operations are conducted in the batch edit mode. All these settings are specified using the fields of the editing configuration object.


                                    

                                    

elementAttr

Specifies the attributes to be attached to the widget's root element.

Type: Object
Default Value: {}

You can configure this option in an ASP.NET MVC Control as follows:

Razor C#
Razor VB
@(Html.DevExtreme().WidgetName()
    .ElementAttr("class", "class-name")
    // ===== or =====
    .ElementAttr(new {
        @id = "elementId",
        @class = "class-name"
    })
    // ===== or =====
    .ElementAttr(new Dictionary<string, object>() {
        { "id", "elementId" },
        { "class", "class-name" }
    })

)
@(Html.DevExtreme().WidgetName() _
    .ElementAttr("class", "class-name")
    ' ===== or =====
    .ElementAttr(New With {
        .id = "elementId",
        .class = "class-name"
    })
    ' ===== or =====
    .ElementAttr(New Dictionary(Of String, Object) From {
        { "id", "elementId" },
        { "class", "class-name" }
    })
)

errorRowEnabled

Indicates whether to show the error row.

Type: Boolean
Default Value: true

The error row displays data-related errors that may occur on the server during the widget's runtime. Setting this option to false hides the error row, but the errors can still be viewed in the browser's console.

See Also

export

Configures client-side export.

Type: Object

When client-side export is enabled, the grid toolbar contains the Export button ( DevExtreme DataGrid HTML5 Toolbar Exporting ) that exports grid data to Excel. For details on exporting, refer to the Client-Side Exporting article.

NOTE
Client-side export requires the JSZip library. Learn where you can get it from topics in the Installation section.

View Demo Watch Video

filterRow

Configures the filter row.

Type: Object

The filter row allows a user to filter data by values of individual columns.

DevExtreme HTML5 JavaScript jQuery Angular Knockout Widget DataGrid FilterRow

Each cell in the filter row contains a magnifying glass icon, pausing on which opens a drop-down list with filters available for the column.

DevExtreme HTML5 JavaScript jQuery Angular Knockout Widget DataGrid FilterRow

To make the filter row visible, assign true to the filterRow.visible option.

View Demo

See Also
Show Example:
AngularJS
Knockout
jQuery

In this example, the filter row is made visible by setting the filterRow.visible option to true. In addition, a filter operation is selected for each grid column from code using the selectedFilterOperation option. This operation can not be changed at runtime, because the filterRow.showOperationChooser option is set to false.


                                    

                                    

In this example, the filter row is made visible by setting the filterRow.visible option to true. In addition, a filter operation is selected for each grid column from code using the selectedFilterOperation option. This operation can not be changed at runtime, because the filterRow.showOperationChooser option is set to false.


                                    

                                    

In this example, the filter row is made visible by setting the filterRow.visible option to true. In addition, a filter operation is selected for each grid column from code using the selectedFilterOperation option. This operation can not be changed at runtime, because the filterRow.showOperationChooser option is set to false.


                                    

                                    

focusStateEnabled

Specifies whether the widget can be focused using keyboard navigation.

Type: Boolean
Default Value: false

grouping

Specifies grouping settings and the behavior of grouped grid records.

Type: Object

An end-user can group data using the group panel, the context menu appearing by a click on a column header, or both. The following list provides an overview of grouping settings that you can specify using the grouping object.

  • Enabling
    To enable grouping using the context menu, assign true to the contextMenuEnabled option. Also, you can enable grouping using the group panel. For this purpose, assign true or "auto" to the groupPanel.visible option.

    jQuery
    JavaScript
    $(function () {
        $("#dataGridContainer").dxDataGrid({
            grouping: {
                contextMenuEnabled: true 
            },
            groupPanel: {
                visible: true 
            }
        });
    });
    Angular
    HTML
    TypeScript
    <dx-data-grid ... >
        <dxo-grouping [contextMenuEnabled]="true"></dxo-grouping>
        <dxo-group-panel [visible]="true"></dxo-group-panel>
    </dx-data-grid>
    import { DxDataGridModule } from 'devextreme-angular';
    // ...
    export class AppComponent {
        // ...
    }
    @NgModule({
        imports: [
            // ...
            DxDataGridModule
        ],
        // ...
    })

    If you need to disable grouping for an individual column, assign false to the allowGrouping property of this column.

  • Behavior
    There are two modes defining how the user expands/collapses groups. The "buttonClick" mode is suitable for medium- and large-screen devices. The "rowClick" mode is designed for small-screen devices, though it performs perfectly on the others as well. For more information on these modes, see the expandMode option.

    jQuery
    JavaScript
    $(function () {
        $("#dataGridContainer").dxDataGrid({
            grouping: {
                // ...
                expandMode: 'buttonClick' // or 'rowClick'
            }
        });
    });
    Angular
    HTML
    TypeScript
    <dx-data-grid ... >
        <dxo-grouping [expandMode]="buttonClick"></dxo-grouping> <!-- or 'rowClick' -->
    </dx-data-grid>
    import { DxDataGridModule } from 'devextreme-angular';
    // ...
    export class AppComponent {
        // ...
    }
    @NgModule({
        imports: [
            // ...
            DxDataGridModule
        ],
        // ...
    })

    A group can appear either expanded or collapsed initially. To specify that, use the autoExpandAll option. Also, you can disallow the user to collapse groups. For this purpose, assign false to the allowCollapsing option.

    jQuery
    JavaScript
    $(function () {
        $("#dataGridContainer").dxDataGrid({
            grouping: {
                // ...
                autoExpandAll: true, 
                allowCollapsing: false 
            }
        });
    });
    Angular
    HTML
    TypeScript
    <dx-data-grid ... >
        <dxo-grouping 
            [autoExpandAll]="true" 
            [allowCollapsing]="false">
        </dxo-grouping>
    </dx-data-grid>
    import { DxDataGridModule } from 'devextreme-angular';
    // ...
    export class AppComponent {
        // ...
    }
    @NgModule({
        imports: [
            // ...
            DxDataGridModule
        ],
        // ...
    })

    Additionally, you can collapse/expand grid groups from code using the collapseAll(groupIndex) and expandAll(groupIndex) methods.

See Also

View Demo

Show Example:
AngularJS
Knockout
jQuery

In this example, groups appear collapsed when you group grid records, because the autoExpandAll option of the grouping object is set to false.


                                    

                                    

In this example, groups appear collapsed when you group grid records, because the autoExpandAll option of the grouping object is set to false.


                                    

                                    

In this example, groups appear collapsed when you group grid records, because the autoExpandAll option of the grouping object is set to false.


                                    

                                    

groupPanel

Configures the group panel.

Type: Object

Data in DataGrid can be grouped by one column or by several. Once a column is used for grouping, it is added to the group panel.

By default, the group panel is hidden. To make it visible, set the groupPanel.visible option to true. Alternatively, the visibility of the group panel can depend on the device's screen size. To accomplish this behavior, set the visible option to "auto".

In case you need to show the group panel, but make it irresponsive, assign false to the groupPanel.allowColumnDragging option. This is useful, for instance, when grid records are grouped initially and when the user needs to know about that grouping, but must not be able to change it.

See Also

View Demo

Show Example:
AngularJS
Knockout
jQuery

In this example, grid records are initially grouped by the Format column. In addition, the group panel is made visible using the groupPanel.visible option. However, the capability to drag columns onto and from the group panel is disabled by setting the groupPanel.allowColumnDragging option to false. Thus, a user can only see how grid records are grouped, but cannot change the initial grouping.


                                    

                                    

In this example, grid records are initially grouped by the Format column. In addition, the group panel is made visible using the groupPanel.visible option. However, the capability to drag columns onto and from the group panel is disabled by setting the groupPanel.allowColumnDragging option to false. Thus, a user can only see how grid records are grouped, but cannot change the initial grouping.


                                    

                                    

In this example, grid records are initially grouped by the Format column. In addition, the group panel is made visible using the groupPanel.visible option. However, the capability to drag columns onto and from the group panel is disabled by setting the groupPanel.allowColumnDragging option to false. Thus, a user can only see how grid records are grouped, but cannot change the initial grouping.


                                    

                                    

headerFilter

Configures the header filter feature.

Type: Object

A header filter allows a user to filter values in an individual column by including/excluding them in/from the applied filter. A click on a header filter icon invokes a popup menu with all unique values in the column. By selecting or clearing the selection of values in this menu, the user includes/excludes them in/from the filter.

DevExtreme HTML5 JavaScript jQuery Angular Knockout Widget DataGrid HeaderFilter

To make header filter icons visible, assign true to the headerFilter.visible option. Data in the popup menu can be customized using the headerFilter option of a specific column.

View Demo

See Also

height

Specifies the widget's height.

Return Value: Number|String

The widget height.

Default Value: undefined

This option accepts a value of one of the following types.

  • Number
    The height of the widget in pixels.

  • String
    A CSS-accepted measurement of height. For example, "55px", "80%", "auto", "inherit".

  • Function
    A function returning either of the above. For example:

    JavaScript
    height: function() {
        return window.innerHeight / 1.5;
    }
Show Example:
AngularJS
Knockout
jQuery

In this example, you can change the height of the DataGrid widget using the slider above it.


                                    

                                    

In this example, you can change the height of the DataGrid widget using the slider above it.


                                    

                                    

In this example, you can change the height of the DataGrid widget using the slider above it.


                                    

                                    

hint

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

Type: String
Default Value: undefined

hoverStateEnabled

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

Type: Boolean
Default Value: false

Show Example:
AngularJS
Knockout
jQuery

In this example, you can change the value of the hoverStateEnabled option by toggling the check box below. To see the changes, hover over a row in the grid.


                                    

                                    

In this example, you can change the value of the hoverStateEnabled option by toggling the check box below. To see the changes, hover over a row in the grid.


                                    

                                    

In this example, you can change the value of the hoverStateEnabled option by toggling the check box below. To see the changes, hover over a row in the grid.


                                    

                                    

keyExpr

Specifies which data field provides keys for data items. Applies only if data is a simple array.

Type: String|Array
Default Value: undefined

loadPanel

Configures the load panel.

Type: Object

The load panel is displayed while the widget loads data. It consists of a loading indicator and text, both placed on a pane.

DevExtreme HTML5 JavaScript jQuery Angular Knockout Widget DataGrid TreeList LoadPanel

Since the load panel is, in fact, the DevExtreme LoadPanel widget, the loadPanel object can contain any options of this widget along with options described here.

See Also
Show Example:
AngularJS
Knockout
jQuery

In this example, several settings of the load panel are changed using the fields of the loadPanel object. To see the changes, refresh the grid's data source by clicking the "Refresh" button. Data for this example is obtained from www.odata.org.


                                    

                                    

In this example, several settings of the load panel are changed using the fields of the loadPanel object. To see the changes, refresh the grid's data source by clicking the "Refresh" button. Data for this example is obtained from www.odata.org.


                                    

                                    

In this example, several settings of the load panel are changed using the fields of the loadPanel object. To see the changes, refresh the grid's data source by clicking the "Refresh" button. Data for this example is obtained from www.odata.org.


                                    

                                    

masterDetail

Allows you to build a master-detail interface in the grid.

Type: Object

In DataGrid, a master-detail interface supplies a usual data row with an expandable section that contains the details on this data row. In that case, the data row is called "master row", while the section is called "detail section".

To enable the master-detail interface, assign true to the masterDetail.enabled option. After that, specify the template for detail sections using the masterDetail.template option. Templates allow you to place virtually anything into the detail sections. For example, you can display another DataGrid or any other UI widget there. For more information on specifying the template for the detail sections, see the template option description.

View Demo Watch Video

See Also

noDataText

Specifies text shown when the widget does not display any data.

Type: String
Default Value: 'No data'

Show Example:
AngularJS
Knockout
jQuery

In this example, the grid is empty because no data source is assigned to it. You can specify the text to be displayed in the empty grid. Type your text in the text box under the grid. After that, make the text box lose focus by clicking the surrounding area. The typed text will be assigned to the noDataText option and will appear in the grid.


                                    

                                    

In this example, the grid is empty because no data source is assigned to it. You can specify the text to be displayed in the empty grid. Type your text in the text box under the grid. After that, make the text box lose focus by clicking the surrounding area. The typed text will be assigned to the noDataText option and will appear in the grid.


                                    

                                    

In this example, the grid is empty because no data source is assigned to it. You can specify the text to be displayed in the empty grid. Type your text in the text box under the grid. After that, make the text box lose focus by clicking the surrounding area. The typed text will be assigned to the noDataText option and will appear in the grid.


                                    

                                    

onAdaptiveDetailRowPreparing

A handler for the adaptiveDetailRowPreparing event. Executed before an adaptive detail row is rendered.

Type: function
Function parameters:

Information about the event.

Object structure:
component: Object
element: jQuery

The widget's container.

model: Object

The model data. Available only if you use Knockout.

formOptions: Object

The options of the Form widget.

Default Value: null

Adaptive detail rows display information from columns that were hidden when the widget adapted to the screen or container size. Each adaptive detail row contains the Form widget that you can customize within the onAdaptiveDetailRowPreparing handler using the formOptions object. Refer to the Form Configuration section for details on options of the Form widget.

NOTE

The following Form options cannot be specified using formOptions:

See Also

onCellClick

A handler for the cellClick event.

Function parameters:

Information about the event.

Object structure:
component: Object
element: jQuery

The widget's container.

model: Object

Data that is available for binding against the element. Available only in the Knockout approach.

jQueryEvent: jQuery.Event

The jQuery event.

data: Object

The object of the data source represented by the row to which the clicked cell belongs.

key: any

The key of the row. If a field providing keys is not specified in a data source, the whole data object is considered the key.

value: any

The value of the clicked cell as it is specified in a data source.

displayValue: String

The value displayed by the clicked cell. Differs from the value field only when the column to which the clicked cell belongs uses lookup.

text: String

The value of the clicked cell in a string format. Use this field to get the value with applied format.

columnIndex: Number

The current index of the column to which the clicked cell belongs. For more information on how this index is calculated, refer to the Column and Row Indexes topic.

column: Object

The settings of the column to which the clicked cell belongs.

rowIndex: Number

The visible index of the row to which the clicked cell belongs. When you have several pages in a grid, grid rows are indexed beginning with 0 on each page. Note that group cells are also counted as rows and, thus, have row indexes. For further information about row indexes, see the Column and Row Indexes topic.

rowType: String

The type of the row to which the clicked cell belongs. This field equals 'data' for data rows or 'group' for group rows. Use this field to distinguish rows by type.

cellElement: jQuery

The element of the clicked cell.

The settings of the row to which the clicked cell belongs.

Default Value: null

The cellClick event fires when a user clicks a grid cell. When implementing a handling function for this event, use the object passed to this function as its parameter. Among the fields of this object, you can find data relating to the clicked cell.

Alternatively, you can navigate to a specific URL when the cellClick event fires. For this purpose, assign this URL to the onCellClick option.

In addition, you can perform some actions when a user clicks a row. For this purpose, handle the rowClick event.

NOTE
cellClick fires before rowClick.
Show Example:
AngularJS
Knockout
jQuery

In this example, a callback function is assigned to the onCellClick property. This function applies a CSS style to a clicked cell. To see the function in action, click a cell in the grid. You will see the text in this cell become orange.


                                    

                                    

                                    

In this example, a callback function is assigned to the onCellClick property. This function applies a CSS style to a clicked cell. To see the function in action, click a cell in the grid. You will see the text in this cell become orange.


                                    

                                    

                                    

In this example, a callback function is assigned to the onCellClick property. This function applies a CSS style to a clicked cell. To see the function in action, click a cell in the grid. You will see the text in this cell become orange.


                                    

                                    

                                    

onCellHoverChanged

A handler for the cellHoverChanged event.

Type: function
Function parameters:

Information about the event.

Object structure:
component: Object
element: jQuery

The widget's container.

model: Object

Data that is available for binding against the element. Available only in the Knockout approach.

eventType: String

Identifies whether the cell has been hovered over or hovered out. This field equals either "mouseover" or "mouseout".

data: Object

The object of the data source presented by the row to which the current cell belongs.

key: any

The key of the row. If a field providing keys is not specified in a data source, the whole data object is considered the key.

value: any

The value of the current cell as it is specified in the data source.

text: String

The value of the current cell in a string format. Use this field to get the value with an applied format.

displayValue: String

The value displayed by the current cell. Differs from the value field only when the column to which the current cell belongs uses lookup.

columnIndex: Number

The index of the column to which the current cell belongs. For more information on how this index is calculated, refer to the Column and Row Indexes topic.

rowIndex: Number

The visible index of the row to which the current cell belongs. When you have several pages in a grid, grid rows are indexed beginning with 0 on each page. Note that group cells are also counted as rows and, thus, have row indexes. For further information about row indexes, see the Column and Row Indexes topic.

column: Object

The settings of the column to which the current cell belongs.

rowType: String

The type of the row to which the current cell belongs. This field equals 'data' for data rows or 'group' for group rows. Use this field to distinguish rows by type.

cellElement: jQuery

The element of the hovered cell.

The settings of the row to which the cell belongs.

Default Value: null

The cellHoverChanged event fires when the hover state of a grid cell is changed. When implementing a handling function for this event, use the object passed to this function as its parameter. Among the fields of this object, you can find data relating to the cell whose hover state has been changed. For example, to identify whether a cell has been hovered over or hovered out, check the value of the eventType field.

Show Example:
AngularJS
Knockout
jQuery

In this example, a callback function is assigned to the onCellHoverChanged property. Within this function a CSS style is applied to a cell when it is hovered over. Once the cell is hovered out, the style is removed. Thus, this callback function implements a custom hot-track feature for grid cells.


                                    

                                    

                                    

In this example, a callback function is assigned to the onCellHoverChanged property. Within this function a CSS style is applied to a cell when it is hovered over. Once the cell is hovered out, the style is removed. Thus, this callback function implements a custom hot-track feature for grid cells.


                                    

                                    

                                    

In this example, a callback function is assigned to the onCellHoverChanged property. Within this function a CSS style is applied to a cell when it is hovered over. Once the cell is hovered out, the style is removed. Thus, this callback function implements a custom hot-track feature for grid cells.


                                    

                                    

                                    

onCellPrepared

A handler for the cellPrepared event.

Type: function
Function parameters:

Information about the event.

Object structure:
component: Object

The widget instance.

element: jQuery

The widget's container.

model: Object

Data that is available for binding against the element. Available only in the Knockout approach.

data: Object

The object of a data source represented by the row to which the prepared cell belongs. This field is unavailable if the rowType field is set to "header", "filter" or "totalFooter".

key: any

The key of the row. If a field providing keys is not specified in a data source, the whole data object is considered the key. This field is unavailable if the rowType field is set to "header", "filter" or "totalFooter".

value: any

The value of the prepared cell as it is specified in the data source.

displayValue: String

The value displayed by the prepared cell. Differs from the value field only when the column to which the prepared cell belongs uses lookup.

text: String

The value of the current cell in a string format. Use this field to get the value with applied format.

columnIndex: Number

The index of the column to which the prepared cell belongs. For more information on how this index is calculated, refer to the Column and Row Indexes topic.

column: Object

The settings of the column to which the prepared cell belongs.

rowIndex: Number

The visible index of the clicked row. When you have several pages in a grid, grid rows are indexed beginning with 0 on each page. Note that group rows are also counted and, thus, have row indexes. For further information about row indexes, see the Column and Row Indexes topic.

rowType: String

The type of the row to which the prepared cell belongs. This field can be set to one of the following values: "data", "detail", "group", "groupFooter", "header", "filter" or "totalFooter". Use this field to distinguish rows by type.

The settings of the row to which the cell belongs.

isSelected: Boolean

Indicates whether the prepared row is selected. This field is useful if the rowType field is set to "data"

isExpanded: Boolean

Indicates whether or not the group cell is expanded. This field is unavailable if the rowType field is set to "header", "filter" or "totalFooter".

cellElement: jQuery

The element of the prepared cell.

Default Value: null

The cellPrepared event fires after a cell has been rendered. When implementing a handling function for this event, use the object passed to this function as its parameter. Among the fields of this object, you can find data relating to the prepared cell.

View Demo

Show Example:
AngularJS
Knockout
jQuery

In this example, cells that have empty values are colored in cornsilk using a handler assigned to the onCellPrepared property.


                                    

                                    

                                    

In this example, cells that have empty values are colored in cornsilk using a handler assigned to the onCellPrepared property.


                                    

                                    

                                    

In this example, cells that have empty values are colored in cornsilk using a handler assigned to the onCellPrepared property.


                                    

                                    

                                    

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.

Type: function
Function parameters:

Information about the event.

Object structure:
component: Object

The widget instance.

element: jQuery

The widget's container.

model: Object

Data that is available for binding against the element. Available only in the Knockout approach.

Default Value: null

Show Example:
AngularJS
Knockout
jQuery

In this example, you can perform various operations in a grid, including sorting, grouping and filtering. Doing this, you may notice when the function assigned to the onContentReady option is called. This function counts its own invocations and displays this number.


                                    

                                    

In this example, you can perform various operations in a grid, including sorting, grouping and filtering. Doing this, you may notice when the function assigned to the onContentReady option is called. This function counts its own invocations and displays this number.


                                    

                                    

In this example, you can perform various operations in a grid, including sorting, grouping and filtering. Doing this, you may notice when the function assigned to the onContentReady option is called. This function counts its own invocations and displays this number.


                                    

                                    

onContextMenuPreparing

A handler for the contextMenuPreparing event.

Type: function
Function parameters:

Information about the event.

Object structure:
component: Object

The widget instance.

element: jQuery

The widget's container.

model: Object

Data that is available for binding against the element. Available only in the Knockout approach.

items: Array

An array of items to be displayed by the context menu. The item objects must have the fields that are used by the ContextMenu default item template.

target: String

The name of the grid element on which the context menu is invoked: 'headerPanel', 'header', 'content' or 'footer'.

targetElement: jQuery

The cell that has been clicked to invoke the context menu.

columnIndex: Number

The current index of the column to which the clicked cell belongs. For more information on how this index is calculated, refer to the Column and Row Indexes topic.

column: Object

The settings of the column to which the clicked cell belongs.

rowIndex: Number

The visible index of the row to which the clicked cell belongs. When you have several pages in a grid, grid rows are indexed beginning with 0 on each page. Note that group cells are also counted as rows and, thus, have row indexes. For further information about row indexes, see the Column and Row Indexes topic.

The settings of the row to which the clicked cell belongs.

Default Value: null

Assign a function to perform a custom action before a context menu is displayed in the grid. For instance, you can change the set of items in the menu.

Show Example:
AngularJS
Knockout
jQuery

The example demonstrates how to add context menu capabilities for editing, adding and deleting DataGrid rows.


                                    

                                    

The example demonstrates how to add context menu capabilities for editing, adding and deleting DataGrid rows.


                                    

                                    

The example demonstrates how to add context menu capabilities for editing, adding and deleting DataGrid rows.


                                    

                                    

onDataErrorOccurred

A handler for the dataErrorOccurred event. Executed when an error occurs in the data source.

Type: function
Function parameters:

Information on the occurred error.

Object structure:
component: Object
element: jQuery

The widget's container.

model: Object

The model data. Available only if you use Knockout.

The standard Error object that defines the error.

Default Value: null

Handles errors that might occur in the data source. To obtain a human-readable description of the error in the handler, use the error.message field.

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.

Type: function
Function parameters:

Information about the event.

Object structure:
component: Object
element: jQuery

The widget's container.

model: Object

The model data. Available only if you use Knockout.

Default Value: null

onEditingStart

A handler for the editingStart event.

Type: function
Function parameters:

Information about the event.

Object structure:
component: Object

The widget instance.

element: jQuery

The widget's container.

model: Object

Data that is available for binding against the element. Available only in the Knockout approach.

data: Object

The data object of the row.

key: any

The key of the row. If a field providing keys is not specified in a data source, the whole data object is considered the key. If a row has not been transmitted to the data source yet, its key is undefined.

cancel: Boolean

A flag allowing you to prevent the row from switching into the editing state.

column: Object

The options of the column whose cell is switching into the editing state; useful in batch edit mode.

Default Value: null

The editingStart event fires before a row (in row edit mode) or a cell (in batch edit mode) switches into the editing state. When implementing a handler for this event, use the object passed to it as its argument. Among the fields of this object, you can find parameters of the about-to-be-edited row.

If you need to prevent a specific row or cell from switching into the editing state, assign true to the cancel field of the object passed to the handler as the argument.

You can also distinguish rows that exist in the data source from rows that have not yet been transmitted to the data source. For this purpose, use the key field of the object with the row parameters. Not-yet-transmitted rows have this field undefined.

View Demo

Show Example:
AngularJS
Knockout
jQuery

In this example, only buffered rows can be edited. If you try to edit a row that is already in the data source, your attempt will be ignored. This behavior is accomplished by setting the cancel flag depending on the value of the key field inside the onEditingStart function.


                                    

                                    

In this example, only buffered rows can be edited. If you try to edit a row that is already in the data source, your attempt will be ignored. This behavior is accomplished by setting the cancel flag depending on the value of the key field inside the onEditingStart function.


                                    

                                    

In this example, only buffered rows can be edited. If you try to edit a row that is already in the data source, your attempt will be ignored. This behavior is accomplished by setting the cancel flag depending on the value of the key field inside the onEditingStart function.


                                    

                                    

onEditorPrepared

A handler for the editorPrepared event.

Type: function
Function parameters:
options: Object

Information about the event.

Object structure:
component: Object

The widget instance.

element: jQuery

The widget's container.

model: Object

The model data. Available only when using Knockout.

parentType: String

The editor's location. One of 'dataRow', 'filterRow', 'headerRow' or 'searchPanel'.
Options passed to the handler depend on this value.

value: any

The editor's value.

setValue(newValue): any

A method that you need to call to change the cell value after the editor's value is changed.

updateValueTimeout: Number

Gets and sets the delay between when a user stops typing a filter value, and it is applied. Available if parentType is 'filterRow' or 'searchPanel'.

width: Number

The editor's width; equals null for all parent type editors except for the 'searchPanel'.

disabled: Boolean

Indicates whether the editor is disabled.

rtlEnabled: Boolean

Indicates whether the editor uses a right-to-left representation.

editorElement: jQuery

The editor's container.

readOnly: Boolean

Indicates whether the editor is read-only.

dataField: String

The name of the field that provides data for the column to which the editor belongs.

The properties of the row to which the editor belongs.

Default Value: null

Many grid elements are constructed on editors. For example, the search panel is constructed on a text box, the selection column is built on check boxes in full, etc. Obviously, editors are also used to edit a cell or a row in a grid. When default editors provided by DataGrid do not meet your requirements, you can customize them by changing their settings within the onEditorPrepared function. This function will be called after an editor is created.

When implementing this function, use the object passed to it as its argument. Among the fields of this object, you can find the created editor's options. These options differ depending on the editor's parent element. Check the parentType field of the function's argument to identify the parent element.

When the parentType is 'dataRow' or 'headerRow', you can use the options described in the columns reference section.

NOTE
If you specified the editCellTemplate option, the onEditorPrepared function is not executed when a row or cell switches to the editing state.

onEditorPreparing

A handler for the editorPreparing event.

Type: function
Function parameters:

Information about the event.

Object structure:
component: Object

The widget instance.

element: jQuery

The widget's container.

model: Object

The model data. Available only if you use Knockout.

parentType: String

The editor's location. One of 'dataRow', 'filterRow', 'headerRow' or 'searchPanel'.
Options passed to the handler depend on this value.

value: any

The editor's value.

setValue(newValue): any

A method that you should call to change the cell value after the editor's value is changed.

updateValueTimeout: Number

Gets and sets the delay between the moment a user stops typing a filter value and the moment it is applied. Available if parentType is 'filterRow' or 'searchPanel'.

width: Number

The editor's width; equals null for editors of all parent types except for the 'searchPanel'.

disabled: Boolean

Indicates whether the editor is disabled.

rtlEnabled: Boolean

Indicates whether the editor uses a right-to-left representation.

cancel: Boolean

Allows you to cancel the creation of the editor.
Set it to true and implement a custom editor if your scenario requires it.

editorElement: jQuery

The editor's container.

readOnly: Boolean

Indicates whether the editor is read-only.

editorName: String

Allows you to change the editor. Accepts names of DevExtreme widgets only, for example, "dxTextBox".

editorOptions: Object

Gets and sets the editor configuration.

dataField: String

The name of the field that provides data for the column to which the editor belongs.

The properties of the row to which the editor belongs.

Default Value: null

Many grid elements are constructed on editors. For example, the search panel is constructed on a text box, the selection column is built on check boxes in full, etc. Obviously, editors are also used to edit a cell or a row in a grid. When default editors provided by DataGrid do not meet your requirements, implement a custom editor. For this purpose, assign a function to the onEditorPreparing option. This function accepts an object as the parameter. Assign true to the cancel field of this object. After that, implement your editor using the other fields of this object.

You can distinguish editors by their parent element. Also, the parent element defines data passed to the onEditorPreparing function. To identify the parent element, check the parentType field of the function's argument.

When the parentType is 'dataRow' or 'headerRow', you can use the options described in the columns reference section.

NOTE
If you have specified the editCellTemplate option, the onEditorPreparing function will not be executed when a row or a cell switches into the editing state.
See Also

onExported

A handler for the exported event.

Type: function
Function parameters:

Information about the event.

Object structure:
component: Object

The widget instance.

element: jQuery

The widget's container.

model: Object

Data that is available for binding against the element. Available only in the Knockout approach.

Default Value: null

Assign a function to perform a custom action after the exporting of the grid data is completed.

See Also

onExporting

A handler for the exporting event.

Type: function
Function parameters:

Information about the event.

Object structure:
component: Object

The widget instance.

element: jQuery

The widget's container.

model: Object

Data that is available for binding against the element. Available only in the Knockout approach.

fileName: String

The name of the file to which grid data is about to be exported.

cancel: Boolean

Indicates whether or not to cancel exporting.

Default Value: null

Assign a function to perform a custom action before exporting grid data.

See Also

onFileSaving

A handler for the fileSaving event.

Type: function
Function parameters:

Information about the event.

Object structure:
component: Object

The widget instance.

element: jQuery

The widget's container.

fileName: String

The name of the file to be saved.

format: String

The format of the file to be saved. Equals 'EXCEL' for an Excel file.

data: BLOB

Exported data as a BLOB.

cancel: Boolean

To cancel file saving, assign true to this parameter.

Default Value: null

Assign a function to perform a custom action before an Excel file with exported data will be saved on the user's local storage.

See Also

onInitialized

A handler for the initialized event. Executed only once, after the widget is initialized.

Type: function
Function parameters:

Information about the event.

Object structure:
component: Object
element: jQuery

The widget's container.

Default Value: null

You cannot access elements in the widget because this handler is executed before they are ready. Use the onContentReady handler instead.

onInitNewRow

A handler for the initNewRow event. Executed before a new row is added to the widget.

Type: function
Function parameters:

Information about the event.

Object structure:
component: Object
element: jQuery

The widget's container.

model: Object

The model data. Available only if you use Knockout.

data: Object

The data of the inserted row; initially empty.

Default Value: null

Using this handler, you can populate a newly added row with data by default. Add fields to the data object so that they correspond to fields of a data source object. Note that the data object may omit some fields present in the data source object. Add only those fields that must initialize specific cells of a new row.

Show Example:
AngularJS
Knockout
jQuery

In this example, you can insert rows into a grid. Before a new row appears, the onInitNewRow function initializes its format data field with a "paperback" value.


                                    

                                    

In this example, you can insert rows into a grid. Before a new row appears, the onInitNewRow function initializes its format data field with a "paperback" value.


                                    

                                    

In this example, you can insert rows into a grid. Before a new row appears, the onInitNewRow function initializes its format data field with a "paperback" value.


                                    

                                    

onKeyDown

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

Type: function
Function parameters:

Information about the event.

Object structure:
component: Object
element: jQuery

The widget's container.

jQueryEvent: jQuery.Event

The original jQuery event.

handled: Boolean

Indicates whether the widget has already handled this event.

Default Value: null

onOptionChanged

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

Type: function
Function parameters:

Information about the event.

Object structure:
component: Object
name: String

A short name of the option whose value has been changed.

fullName: String

A full name of the option whose value has been changed; contains a full hierarchy of the option.

value: any

A new value for the option.

element: jQuery

The widget's container.

model: Object

The model data. Available only if you use Knockout.

Default Value: null

onRowClick

A handler for the rowClick event.

Function parameters:

Information about the event.

Object structure:
component: Object

The widget instance.

element: jQuery

The widget's container.

model: Object

Data that is available for binding against the element. Available only in the Knockout approach.

jQueryEvent: jQuery.Event

The jQuery event.

data: Object

The object of the data source represented by the clicked row.

key: any

The key value of the clicked row.

values: Array

Values of the clicked row as they exist in the data source.

columns: Array

Grid columns. Each column in this array is represented by an object with column settings. The order of columns in this array and columns in the columns array coincides.

rowIndex: Number

The visible index of the clicked row. When you have several pages in a grid, grid rows are indexed beginning with 0 on each page. Note that group rows are also counted and thus have row indexes. For further information about row indexes, see the Column and Row Indexes topic.

rowType: String

The type of the clicked row. This field equals 'data' for data rows, 'group' for group rows or 'detail' for detail sections. Use this field to distinguish rows by type.

isSelected: Boolean

Indicates whether the clicked row is selected.

isExpanded: Boolean

Indicates whether or not the group row is expanded. This field is useful if the rowType field is 'group'.

groupIndex: Number

The group index of the clicked row. This field is useful if the rowType field is 'group'.

rowElement: jQuery

The clicked row; provides access to element-related jQuery operations.

handled: Boolean

Indicates if the grid has already handled the row click event.

Default Value: null

The rowClick event fires when a user clicks a grid row. When implementing a handling function for this event, use the object passed to this function as its parameter. Among the fields of this object, you can find data relating to the clicked row.

Alternatively, you can navigate to a specific URL when the rowClick event fires. For this purpose, assign this URL to the onRowClick option.

NOTE
If there are any internal grid handlers for the row click, the rowClick event fires only after these handlers are executed. In this case, the handled field of the handler function parameter is set to true.

In addition, you can perform certain actions when a user clicks a cell. For this purpose, handle the cellClick event. Note that the cellClick fires before the rowClick.

NOTE
When the clicked row is in the editing state, or switches to the editing state, the rowClick event will not fire. Instead, you can use the cellClick.
Show Example:
AngularJS
Knockout
jQuery

In this example, a callback function is assigned to the onRowClick property. This function applies a CSS style to a clicked row. To see the function in action, click a row in the grid. You will see this row painted gray.


                                    

                                    

                                    

In this example, a callback function is assigned to the onRowClick property. This function applies a CSS style to a clicked row. To see the function in action, click a row in the grid. You will see this row painted gray.


                                    

                                    

                                    

In this example, a callback function is assigned to the onRowClick property. This function applies a CSS style to a clicked row. To see the function in action, click a row in the grid. You will see this row painted gray.


                                    

                                    

                                    

onRowCollapsed

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

Type: function
Function parameters:

Information about the event.

Object structure:
component: Object
element: jQuery

The widget's container.

model: Object

The model data. Available only if you use Knockout.

key: any

The key of the row.

Default Value: null

onRowCollapsing

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

Type: function
Function parameters:

Information about the event.

Object structure:
component: Object
element: jQuery

The widget's container.

model: Object

The model data. Available only if you use Knockout.

key: any

The key of the row.

cancel: Boolean

Allows you to cancel row collapsing.

Default Value: null

To cancel row collapsing, assign true to the cancel field of the handler parameter.

onRowExpanded

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

Type: function
Function parameters:

Information about the event.

Object structure:
component: Object
element: jQuery

The widget's container.

model: Object

The model data. Available only if you use Knockout.

key: any

The key of the row.

Default Value: null

onRowExpanding

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

Type: function
Function parameters:

Information about the event.

Object structure:
component: Object
element: jQuery

The widget's container.

model: Object

The model data. Available only if you use Knockout.

key: any

The key of the group or master row.

cancel: Boolean

Allows you to cancel row expansion.

Default Value: null

To cancel row expansion, assign true to the cancel field of the handler parameter.

onRowInserted

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

Type: function
Function parameters:

Information about the event.

Object structure:
component: Object
element: jQuery

The widget's container.

model: Object

The model data. Available only if you use Knockout.

data: Object

The data of the row.

key: any

The key of the row. If a field providing keys is not specified in the data source, the whole data object is considered the key.

The standard Error object defining an error that may occur during insertion.

Default Value: null
NOTE
In batch editing mode, if several rows have been inserted, this handler will be executed for each row individually.

onRowInserting

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

Type: function
Function parameters:

Information about the event.

Object structure:
component: Object
element: jQuery

The widget's container.

model: Object

The model data. Available only if you use Knockout.

data: Object

The data of the to-be-inserted row.

Allows you to cancel row insertion.

Default Value: null

To cancel row insertion, assign true to the cancel field of the handler parameter. To perform an asynchronous action before inserting a row, assign a jQuery.Promise to the cancel field. The row will be inserted once the Deferred object of this Promise is resolved.

NOTE
In batch editing mode, if several rows are to be inserted, this handler will be executed for each row individually.
Show Example:
AngularJS
Knockout
jQuery

In this example, if you try to save a new row without the "Author" or "Title" field specified, this row will be rejected and the alert dialog box will appear.


                                    

                                    

In this example, if you try to save a new row without the "Author" or "Title" field specified, this row will be rejected and the alert dialog box will appear.


                                    

                                    

In this example, if you try to save a new row without the "Author" or "Title" field specified, this row will be rejected and the alert dialog box will appear.


                                    

                                    

onRowPrepared

A handler for the rowPrepared event.

Type: function
Function parameters:

Information about the event.

Object structure:
component: Object

The widget instance.

element: jQuery

The widget's container.

model: Object

Data that is available for binding against the element. Available only in the Knockout approach.

data: Object

The object of a data source represented by the prepared row. This field is unavailable if the rowType field is set to "header", "filter" or "totalFooter".

key: any

The key of the row. If a field providing keys is not specified in a data source, the whole data object is considered the key. This field is unavailable if the rowType field is set to "header", "filter" or "totalFooter".

values: any

Values of the current row as they exist in the data source.

columns: Array

Grid columns. Each column in this array is represented by an object with column settings. The order of columns in this array and columns in the columns array coincides.

rowIndex: Number

The visible index of the prepared row. When you have several pages in a grid, grid rows are indexed beginning with 0 on each page. Note that group cells are also counted as rows and, thus, have row indexes. For further information about row indexes, see the Column and Row Indexes topic.

rowType: String

The type of the prepared row. This field can be set to one of the following values: "data", "detail", "group", "groupFooter", "header", "filter" or "totalFooter". Use this field to distinguish rows by type.

groupIndex: Number

The group index of the current row. This field is useful if the rowType field is 'group'.

isSelected: Boolean

Indicates whether the prepared row is selected. This field is useful if the rowType field is set to "data"

isExpanded: Boolean

Indicates whether the prepared row is expanded. This field is unavailable if the rowType field is set to "header", "filter" or "totalFooter".

rowElement: jQuery

The element of the hovered row.

Default Value: null

The rowPrepared event fires after a row has been rendered. When implementing a handling function for this event, use the object passed to this function as its parameter. Among the fields of this object, you can find data relating to the prepared row.

Show Example:
AngularJS
Knockout
jQuery

In this example, all grid records that represent books written in the 19th century are colored in silver using the handler assigned to the onRowPrepared property.


                                    

                                    

                                    

In this example, all grid records that represent books written in the 19th century are colored in silver using the handler assigned to the onRowPrepared property.


                                    

                                    

                                    

In this example, all grid records that represent books written in the 19th century are colored in silver using the handler assigned to the onRowPrepared property.


                                    

                                    

                                    

onRowRemoved

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

Type: function
Function parameters:

Information about the event.

Object structure:
component: Object
element: jQuery

The widget's container.

model: Object

The model data. Available only if you use Knockout.

data: Object

The data of the row.

key: any

The key of the row. If a field providing keys is not specified in the data source, the whole data object is considered the key.

The standard Error object defining an error that may occur during removal.

Default Value: null
NOTE
In batch editing mode, if several rows have been removed, this handler will be executed for each row individually.

onRowRemoving

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

Type: function
Function parameters:

Information about the event.

Object structure:
component: Object
element: jQuery

The widget's container.

model: Object

The model data. Available only if you use Knockout.

data: Object

The data of the row.

key: any

The key of the row. If a field providing keys is not specified in the data source, the whole data object is considered the key.

Allows you to cancel row removal.

Default Value: null

To cancel row removal, assign true to the cancel field of the handler parameter. To perform an asynchronous action before removing the row, assign a jQuery.Promise to the cancel field. The row will be removed once the Deferred object of this Promise is resolved.

NOTE
In batch editing mode, if several rows are to be removed, this handler will be executed for each row individually.
Show Example:
AngularJS
Knockout
jQuery

In this example, grid settings allow you to delete rows. Since batch edit mode is set, you can also recover deleted rows. Note that when you save changes, rows that have the format field equaling "hardcover" will not be deleted from the data source and will stay recoverable. It is the result of implementing the onRowRemoving function that prohibits these rows from being deleted.


                                    

                                    

In this example, grid settings allow you to delete rows. Since batch edit mode is set, you can also recover deleted rows. Note that when you save changes, rows that have the format field equaling "hardcover" will not be deleted from the data source and will stay recoverable. It is the result of implementing the onRowRemoving function that prohibits these rows from being deleted.


                                    

                                    

In this example, grid settings allow you to delete rows. Since batch edit mode is set, you can also recover deleted rows. Note that when you save changes, rows that have the format field equaling "hardcover" will not be deleted from the data source and will stay recoverable. It is the result of implementing the onRowRemoving function that prohibits these rows from being deleted.


                                    

                                    

onRowUpdated

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

Type: function
Function parameters:

Information about the event.

Object structure:
component: Object
element: jQuery

The widget's container.

model: Object

The model data. Available only if you use Knockout.

data: Object

The updated data of the row; contains only those fields that have been updated.

key: any

The key of the row. If a field providing keys is not specified in the data source, the whole data object is considered the key.

The standard Error object defining an error that may occur during updating.

Default Value: null
NOTE
In batch editing mode, if several rows have been updated, this handler will be executed for each row individually.

onRowUpdating

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

Type: function
Function parameters:

Information about the event.

Object structure:
component: Object
element: jQuery

The widget's container.

model: Object

The model data. Available only if you use Knockout.

oldData: Object

The old data of the row.

newData: Object

The updated data of the row.

key: any

The key of the row. If a field providing keys is not specified in the data source, the whole data object is considered the key.

Allows you to cancel row updating.

Default Value: null

To cancel row updating, assign true to the cancel field of the handler parameter. To perform an asynchronous action before updating the row, assign a jQuery.Promise to the cancel field. The row will be updated once the Deferred object of this Promise is resolved.

NOTE
In batch editing mode, if several rows are to be updated, this handler will be executed for each row individually.
Show Example:
AngularJS
Knockout
jQuery

In this example, grid settings allow you to edit rows in batch mode. Note that when you save changes, rows that have the format field equaling "hardcover" will not be updated in the data source. It is the result of implementing the onRowUpdating function that prohibits these rows from being updated.


                                    

                                    

In this example, grid settings allow you to edit rows in batch mode. Note that when you save changes, rows that have the format field equaling "hardcover" will not be updated in the data source. It is the result of implementing the onRowUpdating function that prohibits these rows from being updated.


                                    

                                    

In this example, grid settings allow you to edit rows in batch mode. Note that when you save changes, rows that have the format field equaling "hardcover" will not be updated in the data source. It is the result of implementing the onRowUpdating function that prohibits these rows from being updated.


                                    

                                    

onRowValidating

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

Type: function
Function parameters:

Information about the event.

Object structure:
component: Object
element: jQuery

The widget's container.

model: Object

The model data. Available only if you use Knockout.

brokenRules: Array

An array of broken rules. The structure of rule objects is described in the Validation Rules section.

isValid: Boolean

Indicates whether data in all row cells satisfies the validation rules.

key: any

The key of the row. If a field providing keys is not specified in the data source, the whole data object is considered the key.

newData: Object

The data of the validated row after changes.

oldData: Object

The data of the validated row before changes.

errorText: String

An error message to be displayed.

Default Value: null

Use this handler to interfere before a message on the broken validation rules is displayed. For instance, you can perform additional checks in this handler and change the validation result by changing the isValid field of the handler parameter. Or, you can correct the error message using the errorText field of the same parameter.

NOTE
In batch editing mode, if changes in several rows are committed simultaneously, this handler will be executed for each row.
Show Example:
AngularJS
Knockout
jQuery

In this example, grid settings allow you to edit rows. The onRowValidating function checks whether the 'Year' value is less than the current year, and highlights the cell in case this criterion is not satisfied.


                                    

                                    

In this example, grid settings allow you to edit rows. The onRowValidating function checks whether the 'Year' value is less than the current year, and highlights the cell in case this criterion is not satisfied.


                                    

                                    

In this example, grid settings allow you to edit rows. The onRowValidating function checks whether the 'Year' value is less than the current year, and highlights the cell in case this criterion is not satisfied.


                                    

                                    

onSelectionChanged

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

Type: function
Function parameters:

Information about the event.

Object structure:
component: Object
element: jQuery

The widget's container.

model: Object

The model data. Available only if you use Knockout.

currentSelectedRowKeys: Array

The keys of the rows that have been selected.

currentDeselectedRowKeys: Array

The keys of the rows whose selection has been cleared.

selectedRowKeys: Array

The keys of all selected rows.

selectedRowsData: Array

The data of all selected rows.
Does not include calculated values.

Default Value: null

This handler has the following specifics:

  • If a field providing key values is not specified in the data source, the whole data object is considered the key. In this case, all arrays passed to the handler contain data objects instead of keys.
  • When selection is deferred, this handler does not provide access to keys and data.

Call the byKey(key) method to retrieve data.

View Demo

onToolbarPreparing

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

Type: function
Function parameters:

Information about the event.

Object structure:
component: Object
element: jQuery

The widget's container.

model: Object

The model data. Available only if you use Knockout.

toolbarOptions: Object
Default Value: null

This handler allows you to customize the toolbar. Depending on the configuration, the widget may add the following items to the toolbar:

  • DevExtreme HTML5 JavaScript jQuery Angular Knockout Widget DataGrid Toolbar ColumnChooserButton - "columnChooserButton"
  • DevExtreme HTML5 JavaScript jQuery Angular Knockout Widget DataGrid Toolbar AddButton - "addRowButton"
  • DevExtreme HTML5 JavaScript jQuery Angular Knockout Widget DataGrid Toolbar SaveButton - "saveButton"
  • DevExtreme HTML5 JavaScript jQuery Angular Knockout Widget DataGrid Toolbar RevertButton - "revertButton"
  • DevExtreme HTML5 JavaScript jQuery Angular Knockout Widget DataGrid Toolbar Exporting - "exportButton"
  • DevExtreme HTML5 JavaScript jQuery Angular Knockout Widget DataGrid Toolbar ApplyFilterButton - "applyFilterButton"
  • "groupPanel"
  • "searchPanel"

The following code shows how you can customize the toolbar using this handler.

jQuery
JavaScript
$(function() {
    $("#dataGridContainer").dxDataGrid({
        // ...
        onToolbarPreparing: function (e) {
            var toolbarItems = e.toolbarOptions.items;
            // Modifies an existing item
            $.each(toolbarItems, function(_, item) {
                if(item.name === "saveButton") {
                    // Change the item options here
                }
            }); 

            // Adds a new item
            toolbarItems.push({
                widget: 'dxButton', 
                options: { icon: 'user', onClick: function() { ... } },
                location: 'after'
            });
        }
    });
});
Angular
TypeScript
HTML
import { DxDataGridModule } from 'devextreme-angular';
// ...
export class AppComponent {
    onToolbarPreparing (e) { 
        var toolbarItems = e.toolbarOptions.items;
        // Modifies an existing item
        toolbarItems.forEach(function(item) {
            if (item.name === "saveButton") {
                // Change the item options here
            }
        });

        // Adds a new item
        toolbarItems.push({
            widget: 'dxButton', 
            options: { icon: 'user', onClick: function () { ... } },
            location: 'after'
        });
    }
}
@NgModule({
    imports: [
        // ...
        DxDataGridModule
    ],
    // ...
})
<dx-data-grid ...
    (onToolbarPreparing)="onToolbarPreparing($event)">
</dx-data-grid>

View Demo Watch Video

pager

Specifies the options of a grid pager.

Type: Object

A pager is a grid element that allows the user to navigate through grid pages and change their size at runtime. By default, the pager is visible if paging is enabled and you do not use virtual or infinite scrolling. To change the pager's visibility explicitly, use its visible option.

The pager consists of a page navigator and a page size selector. The page navigator contains the numbers of pages. Clicking a page number navigates the user to the page. The page size selector contains the page sizes that can be selected. They are specified by the allowedPageSizes option of the pager configuration object. The page size selector is hidden by default. To make it visible, assign true to the pager's showPageSizeSelector option.

View Demo Watch Video

Show Example:
AngularJS
Knockout
jQuery

In this example, the page size selector is made visible using the pager.showPageSizeSelector option. In addition, the set of allowed page sizes is altered by setting the pager.allowedPageSizes option.


                                    

                                    

In this example, the page size selector is made visible using the pager.showPageSizeSelector option. In addition, the set of allowed page sizes is altered by setting the pager.allowedPageSizes option.


                                    

                                    

In this example, the page size selector is made visible using the pager.showPageSizeSelector option. In addition, the set of allowed page sizes is altered by setting the pager.allowedPageSizes option.


                                    

                                    

paging

Specifies paging options.

Type: Object

In DataGrid, records can be loaded either page by page or all at once. Needless to say that the latter approach affects grid performance, especially when the number of loading records is very large. If you, however, want to use it, disable paging by setting the paging.enabled option to false.

When paging is on, you can specify the size of grid pages using the pageSize option. Additionally, if you require displaying grid records starting with a certain page, assign its index to the pageIndex option.

A paginated grid can be navigated by a user at runtime. For this purpose, he or she can use a pager or scrolling.

View Demo

See Also
Show Example:
AngularJS
Knockout
jQuery

In this example, fields of the paging object are used to specify paging settings. The size of a grid page is set to 8 records using the paging.pageSize option. In addition, the index of a start page is specified using the paging.pageIndex option. Data for this example is obtained from www.odata.org.


                                    

                                    

In this example, fields of the paging object are used to specify paging settings. The size of a grid page is set to 8 records using the paging.pageSize option. In addition, the index of a start page is specified using the paging.pageIndex option. Data for this example is obtained from www.odata.org.


                                    

                                    

In this example, fields of the paging object are used to specify paging settings. The size of a grid page is set to 8 records using the paging.pageSize option. In addition, the index of a start page is specified using the paging.pageIndex option. Data for this example is obtained from www.odata.org.


                                    

                                    

remoteOperations

Specifies the operations that must be performed on the server side.

Default Value: 'auto'

Data for the DataGrid can be stored on the client or come from the server. As a rule, manipulating data on the server enhances DataGrid performance. However, the server might be falling short of implementing certain operations, in which case, they can be performed on the client.

Data operations can be categorized into basic operations (filtering, sorting, paging) and advanced operations (grouping, group paging, summary calculation). The following table shows where data operations are performed by default.

Basic operations Advanced operations
CustomStore client client
ODataStore server client (always)
NOTE
You cannot perform data operations on the server with an ArrayStore, a LocalStore or an array of objects.

To control individual operations, assign a Boolean value to a corresponding field of the remoteOperations object. To control all operations simultaneously, assign a Boolean value directly to the remoteOperations option.

NOTE
If you assign true to remoteOperations, the group paging feature is still performed on the client. To delegate it to the server, assign true to the remoteOperations.groupPaging, but note that with this setting, all other operations are delegated to the server also.
NOTE
If actual data is stored on the server, making data operations local does not guarantee that there won't be any queries for data to the server while these operations are being performed. It only guarantees that calculations will be performed on the client.

Note that when operations are performed remotely, the DataGrid does not support:

View Demo

rowAlternationEnabled

Specifies whether rows should be shaded differently.

Type: Boolean
Default Value: false

All rows are monochrome without any visual distinctions by default. If you set this option to true, ordinary-looking rows will alternate with slightly shaded ones.

View Demo

Show Example:
AngularJS
Knockout
jQuery

In this example, you can change the value of the rowAlternationEnabled option using the check box below.


                                    

                                    

In this example, you can change the value of the rowAlternationEnabled option using the check box below.


                                    

                                    

In this example, you can change the value of the rowAlternationEnabled option using the check box below.


                                    

                                    

rowTemplate

Specifies a custom template for grid rows.

Type: template
Function parameters:
rowElement: jQuery

The row under customization.

rowInfo: Object

The options of the current row.

Use the rowTemplate option to define the markup of all rows in a grid. Implement a callback function defining the content of a grid row and assign it to this option. This function is invoked every time DataGrid rerenders itself.

When implementing the rowTemplate function, you can access the row under customization using the function's first parameter. This parameter provides access to element-related jQuery operations, and you can access row options using the fields of the function's second parameter that are listed below.

  • data
    Contains the object of the data source represented by the current row.
  • component
    Contains the DataGrid instance.
  • values
    Contains an array of values of the current row in the order they exist in the data source.
  • rowIndex
    Contains the index of the current row. When you have several pages in the grid, grid rows are indexed beginning with 0 on each page. Note that group cells count as rows and have row indexes. For further information about row indexes, see the Column and Row Indexes topic.
  • columns
    Contains an array of grid columns. An object with column settings represents each column in this array. The order of columns in this array coincides with the columns array.
  • isSelected
    Indicates whether or not the current row is selected.
  • rowType
    Defines the type of the current row. This field equals 'data' for data rows or 'group' for group rows. Use this field to distinguish rows by type.
  • groupIndex
    Contains the group index of the current row. This field is useful if the rowType field is 'group'.
  • isExpanded
    Indicates whether or not the current row is expanded. This field is useful if the rowType field is 'group'.

When utilizing the Knockout, Angular or AngularJS library in your application, you can specify the row template using the dxTemplate markup component. Note that dxTemplate should be bound to a <table> HTML element.

Angular
HTML
TypeScript
<dx-data-grid ...
    rowTemplate="rowTemplateName">
    <tbody *dxTemplate="let data of 'rowTemplateName'" >
        <tr class="dx-row main-row">
            <td>{{data.id}}</td>
            <td>{{data.name}}</td>
        </tr>
    </tbody>
</dx-data-grid>
import { DxDataGridModule } from 'devextreme-angular';
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxDataGridModule
    ],
    // ...
})
AngularJS
HTML
<div dx-data-grid="{
        <!-- other grid settings go here -->
        rowTemplate: 'rowTemplateName'
    }" dx-item-alias="item">
        <table data-options="dxTemplate: { name: 'rowTemplateName' }" >
            <tr>
                <td>{{item.id}}</td>
                <td>{{item.name}}</td>
            </tr>
        </table>
    </div>
Knockout
HTML
<div data-bind="dxDataGrid: {
        <!-- other grid settings go here -->
        rowTemplate: 'rowTemplateName'
    }">
        <table data-options="dxTemplate: { name: 'rowTemplateName' }" >
            <tr>
                <td data-bind="text: id"></td>
                <td data-bind="text: name"></td>
            </tr>
        </table>
    </div>

It is also possible to define a row template in markup. For this purpose, use one of the following template engines. The cell settings mentioned above can be accessed in a similar manner inside the template.

Using a template engine, pass one of the following values to the rowTemplate option:

  • A jQuery object representing the template's container.
  • A DOM Node representing the template's container.
  • A function that returns a jQuery object or a DOM Node representing the template's container.

When you implement a row template with a template engine, take into account certain specifics. Particularly, the <tr> element that represents a row should have the dx-row class for correct operation of all widget features.

View Demo

NOTE
When you use a row template, we recommend you disable the column reordering, grouping, and column fixing features. The template's content cannot automatically synchronize with the column layout, which makes these features inoperative.

To customize a row without defining the entire template, handle the rowPrepared event.

rtlEnabled

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

Type: Boolean
Default Value: false

When this option is set to true, the widget text flows from right to left, and the layout of elements is reversed. To switch the entire application/site to the right-to-left representation, assign true to the rtlEnabled field of the object passed to the DevExpress.config(config) method.

JavaScript
DevExpress.config({
    rtlEnabled: true
});
Show Example:
AngularJS
Knockout
jQuery

In this example, you can change the value of the rtlEnabled option at runtime using the check box under the grid.


                                    

                                    

In this example, you can change the value of the rtlEnabled option at runtime using the check box under the grid.


                                    

                                    

In this example, you can change the value of the rtlEnabled option at runtime using the check box under the grid.


                                    

                                    

scrolling

Configures scrolling.

Type: Object

Scrolling allows a user to browse data left outside the current viewport. The widget provides several scrolling modes detailed in the mode option description.

View Demo

See Also

searchPanel

Configures the search panel.

Type: Object

The search panel allows searching for values in several columns at once. The widget searches against only those columns whose allowSearch option is set to true.

DevExtreme HTML5 JavaScript jQuery Angular Knockout Widget DataGrid SearchPanel

To make the search panel visible, set the searchPanel.visible option to true.

View Demo

See Also
Show Example:
AngularJS
Knockout
jQuery

In this example, the search panel is made visible using the visible option of the searchPanel object. Additionally, its width is changed using the width option of the same object.


                                    

                                    

In this example, the search panel is made visible using the visible option of the searchPanel object. Additionally, its width is changed using the width option of the same object.


                                    

                                    

In this example, the search panel is made visible using the visible option of the searchPanel object. Additionally, its width is changed using the width option of the same object.


                                    

                                    

selectedRowKeys

Specifies the keys of rows that must be selected initially. Applies only if selection.deferred is false.

Type: Array

To access a row by its key, you should specify the field that provides keys. For this, use the key option of the Store that underlies the dataSource. If no key was specified, the whole data object is considered the key. However, we recommend specifying the key option to prevent selection from being duplicated.

See Also
Show Example:
AngularJS
Knockout
jQuery

In this example, several grid records appear selected initially. It is accomplished by assigning their keys in the form of an array to the selectedRowKeys option.


                                    

                                    

In this example, several grid records appear selected initially. It is accomplished by assigning their keys in the form of an array to the selectedRowKeys option.


                                    

                                    

In this example, several grid records appear selected initially. It is accomplished by assigning their keys in the form of an array to the selectedRowKeys option.


                                    

                                    

selection

Configures runtime selection.

Type: Object

A user can select rows in a single or multiple mode. In multiple mode, a user can select all rows at once. To disable this feature, assign false to the allowSelectAll.

By default, once a user selects a row, the data source is instantly notified about it. This may lower the widget performance if the data source is remote and the user is allowed to select all rows at once. In this case, we recommend making the selection deferred.

View Demo

See Also

selectionFilter

Specifies filters for the rows that must be selected initially. Applies only if selection.deferred is true.

Default Value: []

This option also allows you to obtain filter expressions for the currently selected rows. Note that if all records are selected, the selectionFilter value is null. If there are no selected records, the value contains an empty array.

See Also

showBorders

Specifies whether the outer borders of the widget are visible.

Type: Boolean
Default Value: false

Show Example:
AngularJS
Knockout
jQuery

In this example, you can change the visibility of grid borders by toggling the check box below.


                                    

                                    

In this example, you can change the visibility of grid borders by toggling the check box below.


                                    

                                    

In this example, you can change the visibility of grid borders by toggling the check box below.


                                    

                                    

showColumnHeaders

Specifies whether column headers are visible.

Type: Boolean
Default Value: true
See Also
Show Example:
AngularJS
Knockout
jQuery

In this example, you can change the visibility of column headers by toggling the check box below.


                                    

                                    

In this example, you can change the visibility of column headers by toggling the check box below.


                                    

                                    

In this example, you can change the visibility of column headers by toggling the check box below.


                                    

                                    

showColumnLines

Specifies whether vertical lines that separate one column from another are visible.

Type: Boolean
Default Value: true
NOTE
If you use the Android or iOS theme, specifying this option doesn't affect anything. These themes avoid displaying column lines in order to provide a native look for the widget. In case you still require the column lines to be displayed, choose another theme.
Show Example:
AngularJS
Knockout
jQuery

In this example, you can change the visibility of the lines that separate grid columns by toggling the check box below.


                                    

                                    

In this example, you can change the visibility of the lines that separate grid columns by toggling the check box below.


                                    

                                    

In this example, you can change the visibility of the lines that separate grid columns by toggling the check box below.


                                    

                                    

showRowLines

Specifies whether horizontal lines that separate one row from another are visible.

Type: Boolean
Default Value: false
Default for ios: true

Show Example:
AngularJS
Knockout
jQuery

In this example, you can change the visibility of the lines that separate grid rows by toggling the check box below.


                                    

                                    

In this example, you can change the visibility of the lines that separate grid rows by toggling the check box below.


                                    

                                    

In this example, you can change the visibility of the lines that separate grid rows by toggling the check box below.


                                    

                                    

sortByGroupSummaryInfo[]

Allows you to sort groups according to the values of group summary items.

Type: Array
Default Value: undefined

Normally, when records are grouped by a column, the groups are sorted according to the values of this column. In a number of cases, such approaches cannot address your needs, e.g., when you require to sort groups by the number of records in each. For these cases, you can implement sorting according to the values of group summary items. These items are specified in the groupItems array. Assume that you have the following code that specifies three group summary items.

jQuery
JavaScript
$(function () {
    $("#dataGridContainer").dxDataGrid({
        // ...
        summary: {
            groupItems: [{
                column: 'Age',
                summaryType: 'avg',
                name: 'Average Age Group Summary'
            }, {
                column: 'Income',
                summaryType: 'max'
            }, {
                column: 'Tasks',
                summaryType: 'min'
            }]
        }
    });
});
Angular
HTML
TypeScript
 <dx-data-grid ... >
     <dxo-summary>
         <dxi-group-item
             column="Age"
             summaryType="avg"
             name="Average Age Group Summary">
         </dxi-group-item>
         <dxi-group-item
             column="Income"
             summaryType="max">
         </dxi-group-item>
         <dxi-group-item
             column="Tasks"
             summaryType="min">
         </dxi-group-item>
     </dxo-summary>
 </dx-data-grid>
import { DxDataGridModule } from 'devextreme-angular';
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxDataGridModule
    ],
    // ...
})

To use these summary items for sorting groups, assign an array of objects to the sortByGroupSummaryInfo option. In each object of this array, specify the summaryItem field. This field determines the summary item to be used for summary-based sorting. In the following code, three objects form the sortByGroupSummaryInfo array. In each object, the summaryItem option determines different summary items using different values.

jQuery
JavaScript
$(function () {
    $("#dataGridContainer").dxDataGrid({
        // ...
        sortByGroupSummaryInfo: [
            { summaryItem: 1 }, // determines the maximum income item using its index in the "groupItems" array
            { summaryItem: 'min' }, // determines the minimum tasks item using its aggregate function
            { summaryItem: 'Average Age Group Summary' } // determines the average age item using its name
        ]
    });
});
Angular
HTML
TypeScript
<dx-data-grid ... >
    <dxi-sort-by-group-summary-info 
        [summaryItem]="1"> <!-- determines the maximum income item using its index in the "groupItems" array -->
    </dxi-sort-by-group-summary-info>
    <dxi-sort-by-group-summary-info 
        summaryItem="min"> <!-- determines the minimum tasks item using its aggregate function -->
    </dxi-sort-by-group-summary-info>
    <dxi-sort-by-group-summary-info 
        summaryItem="Average Age Group Summary"> <!-- determines the average age item using its name -->
    </dxi-sort-by-group-summary-info>
</dx-data-grid>
import { DxDataGridModule } from 'devextreme-angular';
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxDataGridModule
    ],
    // ...
})

After that, set the groupColumn option for objects in the sortByGroupSummaryInfo array. This option identifies the column that must be used in grouping in order that a particular summary-based sorting setting be applied. If you have omitted this option from an object, the sorting setting specified by this object will be applied regardless of the column used in grouping.

jQuery
JavaScript
$(function () {
    $("#gridContainer").dxDataGrid({
        // ...
        sortByGroupSummaryInfo: [
            { summaryItem: 1, groupColumn: 'Tasks' }, // applies sorting only when records are grouped by the "Tasks" column
            { summaryItem: 'min', groupColumn: 'Last Name' }, // applies sorting only when records are grouped by a "Last Name" column
            { summaryItem: 'Average Age Group Summary' } // applies sorting regardless the grouping column
        ]
    });
});
Angular
HTML
TypeScript
<dx-data-grid ... >
    <dxi-sort-by-group-summary-info 
        [summaryItem]="1" groupColumn="Tasks"> <!-- applies sorting only when records are grouped by the "Tasks" column -->
    </dxi-sort-by-group-summary-info>
    <dxi-sort-by-group-summary-info 
        summaryItem="min"
        groupColumn="Last Name"> <!-- applies sorting only when records are grouped by a "Last Name" column -->
    </dxi-sort-by-group-summary-info>
    <dxi-sort-by-group-summary-info 
        summaryItem="Average Age Group Summary"> <!--  applies sorting regardless the grouping column -->
    </dxi-sort-by-group-summary-info>
</dx-data-grid>
import { DxDataGridModule } from 'devextreme-angular';
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxDataGridModule
    ],
    // ...
})
NOTE
If several summary-based sorting settings match the current grouping, their indexes in the sortByGroupSummaryInfo array will dictate the order of their application.

In addition, you can set an ascending or descending sort order for each summary-based sorting object using its sortOrder option.

See Also

-Sort by Group Summary

sorting

Configures runtime sorting.

Type: Object

A user can sort rows by values of a single or multiple columns depending on the value of the sorting.mode option.

DevExtreme HTML5 JavaScript jQuery Angular Knockout Widget DataGrid Sorting

To apply sorting to a column, a user clicks its header or selects a command from the context menu.

DevExtreme HTML5 JavaScript jQuery Angular Knockout Widget DataGrid Sorting

View Demo

See Also
Show Example:
AngularJS
Knockout
jQuery

In this example, you can sort grid records by multiple columns as the sorting.mode option is set to 'multiple'. To sort records by only one column, click a column header. To sort records by multiple columns, right-click a column header and choose a sort order for the column.


                                    

                                    

In this example, you can sort grid records by multiple columns as the sorting.mode option is set to 'multiple'. To sort records by only one column, click a column header. To sort records by multiple columns, right-click a column header and choose a sort order for the column.


                                    

                                    

In this example, you can sort grid records by multiple columns as the sorting.mode option is set to 'multiple'. To sort records by only one column, click a column header. To sort records by multiple columns, right-click a column header and choose a sort order for the column.


                                    

                                    

stateStoring

Specifies options of state storing.

Type: Object

At runtime, end-users may adjust user interface settings to their needs. By default, these settings disappear when you dispose of the grid; on next loading, the grid appears in its original configuration. If user settings need to be saved and then restored, enable client-side state storing for the grid by setting the stateStoring.enabled option to true. The grid state will be saved under a specified storage key. The saving operation is conducted after a certain amount of time has passed since the last change of the state. To specify the amount of time in milliseconds, use the savingTimeout option.

DataGrid supports various types of state storing. The type of storage that will suit your needs best depends on the supposed lifetime of user-specified grid settings. For more information about state storing types, refer to the type option description.

DataGrid provides the state method to operate the grid state in code. Call this method without arguments to obtain the grid state. When you need to set the grid state, call this method with the state object as its argument. You can also return the widget to its default state by calling the state method with the empty array or null argument.

View Demo

summary

Specifies the options of the grid summary.

Type: Object

A summary is a grid feature that provides a synopsis of data contained in the grid. A summary consists of several items. A summary item displays a value that is a product of applying an aggregate function to the data of a specific column.

There are two types of summary in DataGrid: group and total. The group summary is calculated on a group of data, which is segregated during grouping. To specify the items of the group summary, declare an array of objects and assign it to the summary.groupItems field.

The total summary is calculated on all data contained in the grid. To specify the items of the total summary, declare an array of objects and assign it to the summary.totalItems field.

Watch Video

tabIndex

Specifies the number of the element when the Tab key is used for navigating.

Type: Number
Default Value: 0

The value of this option will be passed to the tabindex attribute of the HTML element that underlies the widget.

twoWayBindingEnabled

Specifies whether to enable two-way data binding.

Type: Boolean
Default Value: true

Two-way data binding ensures that the UI tracks changes made in the data source by a 3rd-party component, and vice versa. This way, the widget and its data source stay synchronized. If you implement two-way data binding in the widget on your own using the cellTemplate and/or editCellTemplate options, make sure to set the twoWayBindingEnabled option to false.

NOTE
The widget provides two-way data binding through Knockout, Angular or AngularJS resources, so make sure to add these libraries to your app.

visible

Specifies whether the widget is visible.

Type: Boolean
Default Value: true

Show Example:
AngularJS
Knockout
jQuery

In this example, you can change the visibility of the DataGrid widget at runtime by toggling the check box above.


                                    

                                    

In this example, you can change the visibility of the DataGrid widget at runtime by toggling the check box above.


                                    

                                    

In this example, you can change the visibility of the DataGrid widget at runtime by toggling the check box above.


                                    

                                    

width

Specifies the widget's width.

Return Value: Number|String

The widget width.

Default Value: undefined

This option accepts a value of one of the following types.

  • Number
    The width of the widget in pixels.

  • String
    A CSS-accepted measurement of width. For example, "55px", "80%", "auto", "inherit".

  • Function
    A function returning either of the above. For example:

    JavaScript
    width: function() {
        return window.innerWidth / 1.5;
    }
Show Example:
AngularJS
Knockout
jQuery

In this example, you can change the width of the DataGrid widget using the slider above it.


                                    

                                    

In this example, you can change the width of the DataGrid widget using the slider above it.


                                    

                                    

In this example, you can change the width of the DataGrid widget using the slider above it.


                                    

                                    

wordWrapEnabled

Specifies whether text that does not fit into a column should be wrapped.

Type: Boolean
Default Value: false

Show Example:
AngularJS
Knockout
jQuery

In this example, you can change the value of the wordWrapEnabled option at runtime by toggling the check box below.


                                    

                                    

In this example, you can change the value of the wordWrapEnabled option at runtime by toggling the check box below.


                                    

                                    

In this example, you can change the value of the wordWrapEnabled option at runtime by toggling the check box below.