Configuration

This section describes the configuration options of the DataGrid widget.

accessKey

Specifies a shortcut key that sets focus on the widget element.

Type: String
Default Value: null

The accessKey option value is passed to the accesskey attribute of the actual HTML element of the widget.

activeStateEnabled

A Boolean value specifying 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 or not grid columns can be reordered by a user.

Type: Boolean
Default Value: false

Initially, grid columns appear in the order specified by the columns array. When this array is not specified, grid columns have the same order as the fields of the first object from the data source. You can provide the capability for a user to reorder grid columns. To enable this capability, set the allowColumnReordering option to true. After that, grid columns can be reordered by dragging their headers.

Once enabled, all grid columns can be reordered by drag-and-drop. If you need to restrict a specific column from being reordered, set the allowReordering option of this column to false.

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 or not grid columns can be resized by a user.

Type: Boolean
Default Value: false

By default, the width of each grid column is calculated automatically, depending on the width of the widget's container and the total number of grid columns. To specify the width of a specific column in code, use the columns | width option. You can allow a user to resize columns at runtime. To enable this capability, set the allowColumnResizing option to true. After that, each grid column can be resized by dragging its border.

Once enabled, column resizing will be allowed for all grid columns. If you need to restrict a specific column from being resized, set the allowResizing option of this column to false.

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 or not to enable data caching.

Type: Boolean
Default Value: true

When this option is enabled, data loaded once is saved to the cache, then the grid uses this cache when performing such operations as sorting, grouping, paging, etc. Caching is helpful when the data source is very large and takes significant time to load.

To force a cache update, use the refresh() method or reload the dataSource.

Consider disabling this feature if your grid displays current data and you need to always keep the grid up to date.

NOTE
If you fetch data from a server, some operations on the 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 actions will force DataGrid to query the server for data repeatedly despite caching being enabled. For example, the advanced operations demand data to be reloaded in full from the server to provide correct results.

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 or not the width of grid columns depends on column content.

Type: Boolean
Default Value: false

When this option is set to true, each grid column has a width that is optimal for holding the content of this column. In this case, the width of the widget's container is ignored. This setting may cause the appearance of horizontal scrolling, but only if the content of a row exceeds the width of the widget's container. In this scenario, consider enabling column fixing.

When this option is set to false, all grid columns have the same width, which is calculated using the width of the widget's container.

If grid columns contain text, then this text can be wrapped if column width is exceeded. To enable word wrapping, set true to the wordWrapEnabled option.

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

Specifies the options of a column chooser.

Type: Object

A column chooser is a grid element that allows a user to hide specific grid columns. This element represents a panel that appears when the user clicks DevExtreme DataGrid ColumnChooser, or when the showColumnChooser() method is called.

A grid column must have the allowHiding option set to true so that a user can drag it onto the column chooser panel.

By default, the column chooser is disabled. To enable it, set the enabled option of the columnChooser object to true. Using the width and height options of this object, you can define the size of the column chooser panel.

In addition, you can customize the text displayed by the panel when it is empty using the emptyPanelText option and the text displayed in the title of the panel using the title option.

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

Specifies options for column fixing.

Type: Object

When a total column width is greater than the width of the grid's container, horizontal scrolling appears. This may happen in the following cases:

If you need specific columns to be displayed on screen regardless of the scrolling performed, set the columnFixing | enabled option to true. In this instance, the columns for which the fixed option is set to true will be anchored to the grid's edge. For instance, the command columns, the ones containing check boxes to select rows or links to save/delete rows, will be fixed since their fixed option is set to true.

You can anchor an unlimited number of columns to any grid edge. To specify a required edge, use a column's fixedPosition option.

View Demo

columnHidingEnabled

Specifies whether or not the widget should hide columns in order to adapt to the screen or container size.

Type: Boolean
Default Value: false

Displaying DataGrid 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. In that case, you can enable the widget to hide certain columns automatically if they do not fit into the screen size. For this purpose, assign true to the columnHidingEnabled option. Information from hidden columns will still be avaialble in the adaptive detail row.

For hiding columns, the DataGrid uses the following principles.

  1. The lesser the hidingPriority option value, the higher the probability that this column is hidden.
  2. If column width option is not specified, a column becomes hidden in case its text is larger than the current column width.
  3. If a column has fixed width, it becomes hidden in case its width does not fit the whole grid width.
See Also

Watch Video

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 Specifying Grid Columns 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

customizeColumns

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

Type: function(columns)
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(columns, rows)
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
  • export - configures client-side exporting.
  • onExporting - allows you to request exporting details and prevent exporting.
  • onExported - allows you to notify an end user when exporting is completed.
  • onFileSaving - allows you to access exported data and/or prevent it from being saved into a file on the user's local storage.

dataSource

Specifies a data source for the grid.

Default Value: null

To provide data for a grid, use the dataSource option. This option accepts one of the following.

  • Array of objects
    A simple JavaScript array containing a collection of plain objects. The fields of each object will be used to provide data for corresponding grid columns.

  • 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 and export data to a file, the changes made to data by the map function are ommitted in the exported file. The same occurs while getting data of the selected rows. It is better to use calculated columns instead of mapping.

By default, a column is generated for each field of data source objects, although you can specify a custom array of columns using the columns option. To get more information about specifying grid columns, see the Specifying Grid Columns topic.

When using a data source that changes dynamically, the DataGrid widget cannot track changes. To update the widget in this case, call its refresh() method.

For more information on how to implement a data source and bind it to your grid, refer to the Data Binding topic.

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.


                                    

                                    

disabled

A Boolean value specifying whether or not the widget can respond to user interaction.

Type: Boolean
Default Value: false

Create an observable variable and assign it to this option to specify the availability of the widget at runtime.

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

Contains options that specify how grid content can be changed.

Type: Object

DataGrid supports editing, insertion and the removing of grid values. The availability of performing a certain operation is specified by the allowUpdating, allowAdding and allowDeleting options.

Editing in DataGrid can be performed in four different modes. For a comprehensive overview of them, see the Row Mode, Batch Mode, Cell Mode and Form Mode articles.

See Also
  • For more information about editing settings you can configure, including both edit modes, refer to the Editing in UI topic.
  • To discover how to manage the editing process from code, see the Editing in Code topic.
NOTE
Before allowing a user to edit, insert and remove, make sure your data source supports all these actions.

View Demo

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.


                                    

                                    

errorRowEnabled

Indicates whether to show the error row for the grid.

Type: Boolean
Default Value: true

The error row displays the data errors that occur on the server during the grid's life cycle.

Set this option to false to avoid showing errors to end users. Instead, the error will be displayed in the browser's console. In addition, you can subscribe to the dataErrorOccured event to provide custom actions when data errors occur on the server.

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 Export article.

NOTE
Exporting features require the JSZip library. Please add a reference to this library to your page. You can get it from the js folder of your DevExtreme Package or use the DevExpress CDN as shown below.
HTML
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/jszip/2.6.0/jszip.min.js"></script>

View Demo Watch Video

filterRow

Specifies filter row options.

Type: Object

In DataGrid, an end-user can filter grid records at runtime using the filter row. This row is located below the grid row that contains column captions. By default, the filter row is hidden. To make it appear, set the visible option of the filterRow object to true.

To filter grid records by a value in a grid column, the user must enter the required value (or a part of it) in the filter row cell that belongs to this column. The matched records are determined according to the column's currently selected filter operation. To change this operation, the user must click the magnifying glass icon accompanying each filter row cell and choose the required filter operation from the appeared drop-down list.

NOTE
This feature is not available for hidden columns.
See Also
  • For more information about filtering, refer to the Filtering topic.
  • To discover how to apply a filter from code, see the Filtering in Code topic.

View Demo

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 or not the widget can be focused.

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.

    JavaScript
    var dataGridOptions = {
        // ...
        grouping: {
            // ...
            contextMenuEnabled: true // enables grouping using the context menu
        },
        groupPanel: {
            // ...
            visible: true // enables grouping using the group panel
        }
    };

    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.

    JavaScript
    var dataGridOptions = {
        // ...
        grouping: {
            // ...
            expandMode: 'buttonClick' // 'rowClick'
        }
    };

    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.

    JavaScript
    var dataGridOptions = {
        // ...
        grouping: {
            // ...
            autoExpandAll: true, // makes the groups appear expanded
            allowCollapsing: false // disallows group collapsing
        }
    };

    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
  • grouping | contextMenuEnabled - enables the user to group data using the context menu.
  • columns[] | allowGrouping - disallows grouping for an individual column.
  • grouping - defines the behavior of groups.

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

Specifies options for filtering using a column header filter.

Type: Object

When a column header filter is visible, each column header is accompanied by a filter icon that invokes a dropdown menu. In this menu, all unique values from the current column are listed. An end user can select one or several values for filtering the grid rows.

You can specify the column-level header filtering options using the columns | headerFilter object.

NOTE
This feature is not available for hidden columns.

For details on filtering, refer to the Filtering article.

View Demo

height

Specifies the height of the widget.

Type: Number|String| function
Return Value: Number|String
The widget height.
Default Value: undefined

The option can hold a value of the following types.

  • number
    The height of the widget in pixels

  • string
    A CSS measurement of the widget height (e.g., "55px", "80%", "auto" and "inherit")

  • function
    A function returning the widget height, e.g.,

    JavaScript
    height: function () {
        return baseHeight - 10 + "%";
    });
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 the text of the hint displayed for 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.


                                    

                                    

loadPanel

Specifies options configuring the load panel.

Type: Object

When DataGrid operates with a large number of records or uses a remote storage as a data source, loading data takes time. As data is being prepared, DataGrid displays a load panel.

The load panel consists of a pane, a loading indicator and a text. You can specify whether the pane or loading indicator must be displayed using the showPane or showIndicator options respectively. The text displayed by the load panel can be specified using the text option. Also, you can change the height or width of the load panel using the corresponding options of the loadPanel configuration object.

Additionally, you can show/hide the load panel from code when using the beginCustomLoading(messageText) and endCustomLoading() methods.

Since the grid load panel is practically the DevExtreme LoadPanel widget, you can specify any option belonging to this widget in the loadPanel object.

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

noDataText

Specifies text displayed when a grid does not contain any records.

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.

Type: function
Function parameters:
e: Object
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.
formOptions: Object
Layout options of the dxForm widget.
Default Value: null

Adaptive detail rows display information from columns that were hidden when the widget adapted to the screen or container size. The adaptiveDetailRowPreparing event fires before an adaptive detail row will be rendered. This row contains the Form widget defining the layout of row items. When implementing the event handler, you can access the Form options using the formOptions field of the handler's parameter.

NOTE
There is a number of Form options that you cannot specify using formOptions due to technical restrictions. Those are the following.
- template
- editorType
- any event handler (options whose name starts with "on...")
See Also

onCellClick

A handler for the cellClick event.

Type: function(e) |String
Function parameters:
e: Object
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 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 Calculating the Column Index 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 Grid Rows topic.
rowType: String
The type of the row to which the clicked cell belongs. This field equals 'data' for ordinary 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(e)
Function parameters:
e: Object
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.
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 Calculating the Column Index 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 Grid Rows 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 ordinary 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(e)
Function parameters:
e: Object
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 Calculating the Column Index 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 Grid Rows 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.

Type: function
Function parameters:
e: Object
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 when widget content is ready.

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(e)
Function parameters:
e: Object
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 Calculating the Column Index 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 Grid Rows 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.

Type: function
Function parameters:
e: Object
Information on the occurred error.
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.
The standard Error object that defines the occurred error.
Default Value: null

To handle errors that might occur in the data source, implement a handling function and assign it to the onDataErrorOccurred option. To obtain a human-readable representation of the occurred error, use the message field of the error object passed to the handling function as the parameter's field.

onDisposing

A handler for the disposing event.

Type: function
Function parameters:
e: Object
Provides function parameters.
Object structure:
component: Object
Provides access to the widget instance.
element: jQuery
An HTML element of the widget.
model: Object
Provides access to the 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 when the widget is being removed.

NOTE
The function assigned to this option is executed only if the widget is removed using the remove(), empty(), or html() jQuery methods.

onEditingStart

A handler for the editingStart event.

Type: function(e)
Function parameters:
e: Object
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(options)
Function parameters:
options: Object
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.
parentType: String
Identifies the type of the editor's parent element. Equals 'dataRow', 'filterRow', 'headerRow' or 'searchPanel'. Depending on the value of this field, different options are passed to the onEditorPrepared handling function.
value: any
The current value of the editor.
setValue(newValue): any
A method that should be called to change the cell value when the editor value is changed.
updateValueTimeout: Number
Specifies the delay between the moment a user stops entering a filter value in the filter row or search panel and the moment this value is applied.
width: Number
The width of the editor; equals null for editors of all parent types except for the 'searchPanel'.
disabled: Boolean
Identifies whether or not the editor is disabled.
rtlEnabled: Boolean
Identifies whether or not the editor uses a right-to-left representation.
editorElement: jQuery
Provides access to element-related jQuery operations.
readOnly: Boolean
Identifies whether or not the editor responds to user actions.
dataField: String
The name of the field providing data for the column that the editor belongs to.
The properties of the row that the editor belongs to.
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 options of the created editor. These options differ depending on the parent element of the editor. 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 onEditorPrepared function will not be executed when a row or a cell switches into the editing state.

onEditorPreparing

A handler for the editorPreparing event.

Type: function(e)
Function parameters:
e: Object
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.
parentType: String
Identifies the type of the editor's parent element. Equals 'dataRow', 'filterRow', 'headerRow' or 'searchPanel'. Depending on the value of this field, different options are passed to the editorPreparing handler.
value: any
The current value of the editor.
setValue(newValue): any
A method that should be called to change a cell value when the editor value is changed.
updateValueTimeout: Number
Specifies the delay between the moment a user stops entering a filter value in the filter row or search panel and the moment this value is applied.
width: Number
The width of the editor; equals null for editors of all parent types except for the 'searchPanel'.
disabled: Boolean
Identifies whether or not the editor is disabled.
rtlEnabled: Boolean
Identifies whether or not the editor uses a right-to-left representation.
cancel: Boolean
A flag that 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
Provides access to element-related jQuery operations.
readOnly: Boolean
Identifies whether or not the editor responds to user actions.
editorName: String
The name of the editor widget.
editorOptions: Object
An object with configuration options for the editor widget.
dataField: String
The name of the field providing data for the column that the editor belongs to.
The properties of the row that the editor belongs to.
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 onEditorPrepared function will not be executed when a row or a cell switches into the editing state.

onExported

A handler for the exported event.

Type: function(e)
Function parameters:
e: Object
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
  • customizeExportData - customizes grid columns and data before exporting.
  • onExporting - allows you to request exporting details and prevent exporting.
  • onFileSaving - allows you to access exported data and/or prevent it from being saved into a file on the user's local storage.

onExporting

A handler for the exporting event.

Type: function(e)
Function parameters:
e: Object
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
  • export - configures client-side exporting.
  • customizeExportData - customizes grid columns and data before exporting.
  • onExported - allows you to notify an end user when exporting is completed.
  • onFileSaving - allows you to access exported data and/or prevent it from being saved into a file on the user's local storage.

onFileSaving

A handler for the fileSaving event.

Type: function(e)
Function parameters:
e: Object
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 to '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
  • onExporting - allows you to request exporting details and prevent exporting.
  • onExported - allows you to notify an end user when exporting is completed.

onInitialized

A handler for the initialized event.

Type: function
Function parameters:
e: Object
Provides function parameters.
Object structure:
component: Object
Provides access to the widget instance.
element: jQuery
An HTML element of the widget.
Default Value: null

Assign a function to perform a custom action when the widget is initialized.

onInitNewRow

A handler for the initNewRow event.

Type: function(e)
Function parameters:
e: Object
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
Data of the inserted row; initially empty.
Default Value: null

By default, a row inserted into a grid contains no data. If you need this row to contain some data, e.g., default values of row cells, implement a function handling the initNewRow event. Use the data field of the object passed to this function as the argument to access the data object of the new row. Initially, this data object is empty. Populate this object with data in such a manner that its fields correspond to the fields of a data source object.

NOTE
Populating all fields of the data object is not necessary. Populate only those of them that must initialize the specific cells of a new row.

View Demo

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.

Type: function(e)
Function parameters:
e: Object
Provides function parameters.
Object structure:
component: Object
Provides access to the widget instance.
element: jQuery
An HTML element of the widget.
jQueryEvent: jQuery.Event
Specifies the jQuery event that caused the action execution.
handled: Boolean
Indicates if the grid has already handled the key down event.
Default Value: null

Assign a function to perform a custom action when a key is pressed down when the widget is focused.

onOptionChanged

A handler for the optionChanged event.

Type: function
Function parameters:
e: Object
Provides function parameters.
Object structure:
component: Object
Provides access to the widget instance.
name: String
Specifies the name of the option whose value is changed.
fullName: String
Specifies a full name of the option whose value is changed. The full name is formed by concatenating the names of the options that are presented in the hierarchy of the given option. The names are delimited by commas.
value: any
Specifies a new value for the option.
element: jQuery
An HTML element of the widget.
model: Object
Provides access to the 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 an option of the component is changed.

onRowClick

A handler for the rowClick event.

Type: function(e) |String
Function parameters:
e: Object
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 Grid Rows topic.
rowType: String
The type of the clicked row. This field equals 'data' for ordinary 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 some 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.

Type: function(e)
Function parameters:
e: Object
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.
key: any
The key of the group or master row.
Default Value: null

Assign a function to perform a custom action after a master or group row is collapsed in the grid.

onRowCollapsing

A handler for the rowCollapsing event.

Type: function(e)
Function parameters:
e: Object
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.
key: any
The key of the group or master row.
cancel: Boolean
Indicates whether to cancel collapsing the row.
Default Value: null

Assign a function to perform a custom action before a master or group row is collapsed in the grid. For instance, you can prevent collapsing by setting the cancel field of the object passed as the handler's parameter to true.

onRowExpanded

A handler for the rowExpanded event.

Type: function(e)
Function parameters:
e: Object
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.
key: any
The key of the group or master row.
Default Value: null

Assign a function to perform a custom action after a master or group row is expanded in the grid.

onRowExpanding

A handler for the rowExpanding event.

Type: function(e)
Function parameters:
e: Object
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.
key: any
The key of the group or master row.
cancel: Boolean
Indicates whether to cancel expanding the row.
Default Value: null

Assign a function to perform a custom action before a master or group row is expanded in the grid. For instance, you can prevent expanding by setting the cancel field of the object passed as the handler's parameter to true.

onRowInserted

A handler for the rowInserted event.

Type: function(e)
Function parameters:
e: Object
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
Data 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.
The standard Error object that defines the occurred error.
Default Value: null

The rowInserted event fires after a row has been inserted into the data source. When implementing a handling function for this event, use the object passed to this function as its argument. Among the fields of this object, you can find the key and data of the inserted row.

NOTE
In batch edit mode, when several rows have been inserted, the onRowInserted function will be executed for each row individually.

View Demo

onRowInserting

A handler for the rowInserting event.

Type: function(e)
Function parameters:
e: Object
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 the data source represented by the inserted row.
A flag allowing you to prevent the row from being inserted into the data source.
Default Value: null

The rowInserting event fires before a new grid row is transmitted to the data source. To handle this event, implement a function and assign it to the onRowInserting option. Using the function's argument, you can access the object with information about the event.

Among the fields of this object, you can find the cancel flag that allows you to prevent the row from being transmitted to the data source. In order to accomplish that, set this flag to true. The behavior of rejected rows depends on the edit mode. In row mode, a rejected row does not switch back to the normal state. In batch mode, rejected rows stay buffered. If you need to perform an asynchronous action before saving the newly added row, assign a jQuery.Promise object to the cancel field. The row will be inserted when the jQuery.Promise object is resolved.

NOTE
In batch edit mode, when several rows are to be inserted, the onRowInserting function will be executed for each row individually.

View Demo

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(e)
Function parameters:
e: Object
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 Grid Rows 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.

Type: function(e)
Function parameters:
e: Object
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
Data 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.
The standard Error object that defines the occurred error.
Default Value: null

The rowRemoved event fires after a row has been removed from the data source. When implementing a handling function for this event, use the object passed to this function as its argument. Among the fields of this object, you can find the data and key of the removed row.

NOTE
In batch edit mode, when several rows have been removed, the onRowRemoved function will be executed for each row individually.

View Demo

onRowRemoving

A handler for the rowRemoving event.

Type: function(e)
Function parameters:
e: Object
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
Row's data.
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.
A flag allowing you to prevent the row from being removed from the data source.
Default Value: null

The rowRemoving event fires before a row is removed from a data source. To handle this event, implement a function and assign it to the onRowRemoving option. Using the function's argument, you can access the object with information about the event.

Among the fields of this object, you can find the cancel flag that allows you to prevent the row from being removed from the data source. In order to accomplish that, set this flag to true. The behavior of the rows, whose removal was canceled, depends on the edit mode. In row mode, such a row is preserved. In batch mode, such rows are displayed as recoverable. If you need to perform an asynchronous action before deleting the row, assign a jQuery.Promise object to the cancel field. The row will be actually deleted when the jQuery.Promise object is resolved.

NOTE
In a batch edit mode, when several rows are to be removed, the onRowRemoving function will be executed for each row individually.

View Demo

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.

Type: function(e)
Function parameters:
e: Object
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
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 a data source, the whole data object is considered the key.
The standard Error object that defines the occurred error.
Default Value: null

The rowUpdated event fires after a row has been updated in the data source. 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 the data object and the key value of the updated row. Note that the data object contains only those fields of a row that have been updated.

NOTE
In batch edit mode, when several rows have been updated, the onRowUpdated function will be executed for each row individually.

View Demo

onRowUpdating

A handler for the rowUpdating event.

Type: function(e)
Function parameters:
e: Object
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.
oldData: Object
Row's old data.
newData: Object
Row's updated data.
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.
A flag allowing you to prevent the row from being updated.
Default Value: null

The rowUpdating event fires before a row is updated in a data source. To handle this event, implement a function and assign it to the onRowUpdating option. Using the function's argument, you can access the object with information about the event.

Among the fields of this object, you can find the cancel flag that allows you to prevent the row from being updated. In order to accomplish this, set this flag to true. The behavior of the rows, whose updating was canceled, depends on the edit mode. In row mode, such a row does not switch back to the normal state. In batch mode, changes in such rows stay buffered. If you need to perform an asynchronous action before saving the updated row, assign a jQuery.Promise object to the cancel field. The row will be actually updated when the jQuery.Promise object is resolved.

NOTE
In batch edit mode, when several rows are to be updated, the onRowUpdating function will be executed for each row individually.

View Demo

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.

Type: function(e)
Function parameters:
e: Object
Provides function parameters.
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.
brokenRules: Array
An array of broken rules. The structure of rule objects is described in the Validation Rules section.
isValid: Boolean
Indicates whether all the rules checked for the cells in the current row are satisfied.
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.
newData: Object
Data of the validated row after user changes.
oldData: Object
Data of the validated row as it was before user changes.
errorText: String
The error message to be displayed in the grid's error row.
Default Value: null

When data in a cell or in several cells is changed, the validation rules specified for these cells are checked. Before the validation result (messages on the broken rules) is displayed in the grid, you can interfere by handling the rowValidating event. For instance, you can provide a common text for all the cells where validation rules are not satisfied. This text will be displayed under the validated row in a specially added error row. To provide a common text for a row, specify the errorText field of the event handling function's parameter. In addition, you can change the validation result before it is displayed, by performing an additional check and setting the result to the isValid field of the event handling function's parameter.

In batch mode, when several row updates are committed simultaneously, the rowValidating error fires for each row that has changes.

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.

Type: function(e)
Function parameters:
e: Object
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.
currentSelectedRowKeys: Array
The keys of the rows that have been selected currently.
currentDeselectedRowKeys: Array
The keys of the rows that have been deselected currently.
selectedRowKeys: Array
The keys of all selected rows.
selectedRowsData: Array
The data of all selected rows.
Default Value: null

The selectionChanged event fires when a grid record has been selected/deselected. When implementing a function that handles this event, you can use arrays of keys of those grid records that have been currently selected or deselected. These arrays can be accessed through the fields of the object passed as the function's parameter. Arrays of all selected records and their data are also accessible through the same object.

If a field providing key values is not specified in a data source, the whole data object is considered the key for a grid record. In this case, all arrays passed to the onSelectionChanged function contain data objects instead of keys.

To retrieve data by using a key, use the byKey(key) method.

View Demo

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

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 that you use in your grid can be stored on the client side or come from a remote server. In many cases, manipulating data on a server enhances grid performance. However, your server might be falling short in performing certain operations. In that case, specify to perform them client side using the remoteOperations option.

Remote operations include basic (filtering, sorting and paging) and advanced operations (grouping and summary calculation). Their default settings differ. Whether basic operations are performed on the client or server side by default depends on the type of the data source. The use of an array of objects, an ArrayStore or a LocalStore forces DataGrid to perform basic operations locally. If you use an ODataStore or a CustomStore, basic operations are performed remotely. Advanced operations are performed on the client side by default.

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
When this option is given false or an object with field(s) set to false, corresponding operations are performed locally. Nevertheless, if your actual data is located on a remote server, it will be loaded from this server and saved in the cache after the widget is initialized. Later, the widget may reload data if it will be necessary, for example, when calculating groups or summary.
NOTE
Data operations in DataGrid have mutual dependencies. Therefore, disabling an individual operation does not guarantee that the widget will not query the server during this operation being performed. For example, DataGrid implements grouping by means of basic operations. Therefore, the combination of client-side grouping and server-side basic operations may produce queries to the server.

rowAlternationEnabled

Specifies whether or not grid rows must be shaded in a different way.

Type: Boolean
Default Value: false

By default, all grid rows are displayed on a monochrome area without visual distinctions between them. If you need to distinguish one row from its neighboring rows visually, set the rowAlternationEnabled option to true. In this case, 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 will be 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. In addition, you can access row options using the fields of the function's second parameter. These fields are listed below.

  • data
    Contains the object of the data source represented by the current row.
  • values
    Contains an array of values of the current row as 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 are also counted as rows, and thus have row indexes. For further information about row indexes, see the Grid Rows topic.
  • columns
    Contains an array of 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.
  • isSelected
    Indicates whether or not the current row is selected.
  • rowType
    Represents the type of the current row. This field equals 'data' for ordinary 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 or AngularJS library in your application, you can specify the row template using the dxTemplate markup component. Note that the dxTemplate should be bound to a <table> HTML element.

  • Knockout

    HTML
    <div data-bind="dxDataGrid: {
        rowTemplate: 'rowTemplateName'
    }">
        <table data-options="dxTemplate: { name: 'rowTemplateName' }" >
            <tr>
                <td data-bind="text: data.id"></td>
                <td data-bind="text: data.name"></td>
            </tr>
        </table>
    </div>
  • AngularJS

    HTML
    <div dx-data-grid="{
        rowTemplate: 'rowTemplateName'
    }">
        <table data-options="dxTemplate: { name: 'rowTemplateName' }" >
            <tr>
                <td>{{data.id}}</td>
                <td>{{data.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 above mentioned cell settings 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.
NOTE
When you use a row template, we recommend you to disable the column reordering, grouping and column fixing features. It is desirable because the template content can not be automatically synchronized with the column layout what makes these features inoperative.

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

View Demo

rtlEnabled

Specifies whether or not the current component supports a right-to-left representation.

Type: Boolean
Default Value: false

If you need to switch the display of this DevExtreme component to right-to-left, enable a specifically designed configuration option - rtlEnabled. When this option is set to true, the text flows from right to left, and the layout the component's elements is reversed. To switch the entire application/site to a right-to-left representation, use the static DevExpress.rtlEnabled field.

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

A configuration object specifying scrolling options.

Type: Object

The DataGrid widget supplies a user with an opportunity to scroll grid records. Scrolling can be performed within one page when used in conjunction with the pager or throughout the whole data source. In the latter case, data is still loaded by pages but a user moves through them continuously without noticing it. To specify required scrolling behavior, use the mode property of the scrolling configuration object.

View Demo

Show Example:
AngularJS
Knockout
jQuery

In this example, the infinite scrolling mode is specified for a grid using the scrolling | mode option. Data for this example is obtained from www.odata.org.


                                    

                                    

In this example, the infinite scrolling mode is specified for a grid using the scrolling | mode option. Data for this example is obtained from www.odata.org.


                                    

                                    

In this example, the infinite scrolling mode is specified for a grid using the scrolling | mode option. Data for this example is obtained from www.odata.org.


                                    

                                    

searchPanel

Specifies options of the search panel.

Type: Object

A search panel is a grid element that allows the user to search grid records by a search string. Searching performs in those grid columns that have the allowFiltering option set to true.

The search panel is located in the upper-right corner of the DataGrid widget. To make it visible, set the visible property of the searchPanel configuration object to true.

See Also
  • To discover how to configure the search panel, see the Search Panel topic.
  • For more information about searching, refer to the Searching topic.

Also, you can search grid records by a search string from code. Call the searchByText(text) method to do this.

View Demo

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 the records that must appear selected initially.

Type: Array

Apart from runtime selection, the DataGrid provides the capability to display specific grid records selected initially. For this purpose, specify an array containing the keys of grid records that must appear selected and assign it to the selectedRowKeys field.

NOTE
To access a grid record by a key, a field providing key values must be specified in the key option of the underlying Store of the dataSource. If no key was specified, the whole data object is considered the key, however, we recommend specifying the key to prevent selection from being duplicated.

You can obtain the selected row keys or data objects. For further information, see the getSelectedRowKeys() and getSelectedRowsData() method descriptions.

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

Specifies options of runtime selection.

Type: Object

DataGrid provides users with the capability of selecting grid records at runtime. End-users can perform selection in a single or multiple mode. To specify the required mode, use the mode property of the selection configuration object. You can disable selection completely using the same property.

When the multiple selection mode is specified, a user is capable of selecting all grid records at once using the main check box or the CTRL + A shortcut. To disable this feature, set the allowSelectAll option to false.

Furthermore, you can perform specific actions when a grid record has been selected/deselected. For additional information, refer to the onSelectionChanged option description.

See Also

View Demo

Show Example:
AngularJS
Knockout
jQuery

In this example, you can select multiple records in a grid. This feature is enabled by setting the selection | mode option to "multiple". However, you cannot select all records at once as the allowSelectAll option is set to false.


                                    

                                    

In this example, you can select multiple records in a grid. This feature is enabled by setting the selection | mode option to "multiple". However, you cannot select all records at once as the allowSelectAll option is set to false.


                                    

                                    

In this example, you can select multiple records in a grid. This feature is enabled by setting the selection | mode option to "multiple". However, you cannot select all records at once as the allowSelectAll option is set to false.


                                    

                                    

showBorders

Specifies whether the outer borders of the grid are visible or not.

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 or not.

Type: Boolean
Default Value: true

A column header contains a column caption. For more information about captions, see the columns | caption option description.

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 or not vertical lines separating one grid 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.

View Demo

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 or not horizontal lines separating one grid 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.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    summary: {
        groupItems: [{
            column: 'Age',
            summaryType: 'avg',
            name: 'Average Age Group Summary'
        }, {
            column: 'Income',
            summaryType: 'max'
        }, {
            column: 'Tasks',
            summaryType: 'min'
        }]
    }
});

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.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    summary: {
        groupItems: [ ... ]
    },
    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
    ]
});

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.

JavaScript
$("#gridContainer").dxDataGrid({
    // ...
    summary: {
        groupItems: [ ... ]
    },
    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
    ]
});
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.

sorting

Specifies options of runtime sorting.

Type: Object

In DataGrid, a user can sort records by columns at runtime. To make a column available for sorting, set its allowSorting option to true. Sorting can be executed in various modes. To specify the required mode, use the mode property of the sorting configuration object.

See Also

View Demo

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 widget tab index.

Type: Number
Default Value: 0

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 instrument, and vice versa, the data source gets updated according to changes in the UI. Thus, the widget and its data source can continue to correspond to each other.

NOTE
DataGrid provides this feature through Knockout and AngularJS resources, so make sure that you have added these libraries to your app.

In certain scenarios, you may want to implement two-way data binding in DataGrid on your own. For this purpose, you can specify cellTemplate and/or editCellTemplate options. If so, make sure that you have the twoWayBindingEnabled option set to false.

visible

A Boolean value specifying whether or not 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 width of the widget.

Type: Number|String| function
Return Value: Number|String
The widget width.
Default Value: undefined

The option can hold a value of the following types.

  • numeric
    The widget width in pixels.
  • string
    A CSS measurement of the widget width (e.g., "55px", "80%", "auto" and "inherit").
  • function
    The function returning the widget width. For example, see the following code.

    JavaScript
    width: function () { 
        return baseWidth - 10 + "%";
    }
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.