DataGrid Configuration

    This section describes the configuration options of the dxDataGrid widget.

    activeStateEnabled

    A Boolean value specifying whether or not the widget changes its state when interacting with a user.

    Type: Boolean
    Default Value: true

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

    <div id="gridContainer" style="height:300px; max-width:800px; margin: 0 auto"></div>
    <div id="checkboxContainer" style="height:20px;margin:5px auto;text-align:center">
        <input type="checkbox" id="allowColumnReorderingCheckbox" checked> Allow Column Reordering
    </div>
    $(function () {
        $("#gridContainer").dxDataGrid({
            dataSource: employees,
            columns: [
                { dataField: 'TitleOfCourtesy', caption: 'Title' },
                'FirstName',
                'LastName',
                { dataField: 'Title', caption: 'Position', width: 150 },
                { dataField: 'BirthDate', dataType: 'date', format: 'shortDate' },
                { dataField: 'HireDate', dataType: 'date', format: 'shortDate' }
            ],
            paging: { pageSize: 6 },
            allowColumnReordering: true
        });
    
        $('#allowColumnReorderingCheckbox').change(function () {
            var dataGrid = $('#gridContainer').dxDataGrid('instance');
            dataGrid.option({
                allowColumnReordering: this.checked
            });
        });
    });

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

    <div id="gridContainer" style="height:300px; max-width:800px; margin: 0 auto"></div>
    <div id="checkboxContainer" style="height:20px;margin:5px auto;text-align:center">
        <input type="checkbox" id="allowColumnResizingCheckbox" checked> Allow Column Resizing
    </div>
    $(function () {
        $("#gridContainer").dxDataGrid({
            dataSource: employees,
            columns: [
                { dataField: 'TitleOfCourtesy', caption: 'Title' },
                'FirstName',
                'LastName',
                { dataField: 'Title', caption: 'Position', width: 150 },
                { dataField: 'BirthDate', dataType: 'date', format: 'shortDate' },
                { dataField: 'HireDate', dataType: 'date', format: 'shortDate' }
            ],
            paging: { pageSize: 6 },
            allowColumnResizing: true
        });
    
        $('#allowColumnResizingCheckbox').change(function () {
            var dataGrid = $('#gridContainer').dxDataGrid('instance');
            dataGrid.option({
                allowColumnResizing: this.checked
            });
        });
    });

    cellClick

    Deprecated

    Use the onCellClick option instead.

    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.

    cellHoverChanged

    Deprecated

    Use the onCellHoverChanged option instead.

    cellPrepared

    Deprecated

    Use the onCellPrepared option instead.

    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.

    When this option is set to false, all grid columns have the same width, which is calculated considering 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:
    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.

    <div id="gridContainer" style="height:380px; max-width:800px; margin: 0 auto"></div>
    <div id="checkboxContainer" style="height:20px;margin:5px auto;text-align:center">
        <input type="checkbox" id="columnAutoWidthCheckbox" checked> columnAutoWidth
    </div>
    $(function () {
        $("#gridContainer").dxDataGrid({
            dataSource: orders,
            columns: [
                "OrderID", "CustomerID", "EmployeeID",
                { dataField: "OrderDate", dataType: 'date', format: 'shortDate' },
                { dataField: "RequiredDate", dataType: 'date', format: 'shortDate' },
                { dataField: "ShippedDate", dataType: 'date', format: 'shortDate' },
                "ShipVia", "Freight", "ShipName", "ShipAddress", "ShipCity"
            ],
            paging: { pageSize: 8 },
            columnAutoWidth: true
        });
    
        $('#columnAutoWidthCheckbox').change(function () {
            var dataGrid = $('#gridContainer').dxDataGrid('instance');
            dataGrid.option({
                columnAutoWidth: this.checked
            });
        });
    });

    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 the ColumnChooser ChartJS icon, 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:
    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.

    <div id="gridContainer" style="height:390px; max-width:800px; margin: 0 auto"></div>
    
    $(function () {
        $("#gridContainer").dxDataGrid({
            dataSource: books,
            columns: [
                'author', 'title', 'year', 'genre', 'format',
                { dataField: 'price', visible: false },
                { dataField: 'length', visible: false }
            ],
            paging: { pageSize: 7 },
            columnChooser: {
                enabled: true,
                height: 180,
                width: 400,
                emptyPanelText: 'A place to hide the columns'
            }
        });
    });

    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

    Show Example:
    jQuery

    In this example, grid columns are configured using the columns array. Friendlier names are specified for the headers of the "Invoice Number", "City", "State" and "Employee" columns using the caption property. The "Order Date" column has an explicitly set data type, while the contents of this column are aligned to the right side using the alignment property. The "Invoice Number" and "Employee" columns have fixed widths specified by the width property. Further, the values in the "Sale Amount" column have a currency format as determined by the format property. In addition, the values of the "Employee" column are customized using a callback function assigned to the calculateCellValue property.

    <div id="gridContainer" style="height:390px; max-width:800px; margin: 0 auto"></div>
    
    $(function () {
        $("#gridContainer").dxDataGrid({
            dataSource: ordersNew,
            columns: [{
                dataField: "OrderNumber",
                width: 130,
                caption: "Invoice Number"
            }, {
                dataField: 'OrderDate',
                dataType: 'date',
                alignment: 'right'
            }, {
                dataField: "SaleAmount",
                format: "currency",
            }, {
                caption: 'Employee',
                width: 150,
                calculateCellValue: function (data) {
                    return [data.EmployeePrefix, data.EmployeeFirstName, data.EmployeeLastName].join(' ');
                }
            }, {
                dataField: 'CustomerStoreCity',
                caption: "City"
            }, {
                dataField: 'CustomerStoreState',
                caption: "State"
            }],
            paging: { pageSize: 8 }
        });
    });

    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 dxDataGrid 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's parameter. Fields of each object in this array represent column options identical to the options described in the columns reference section.

    Show Example:
    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.

    <div id="gridContainer" style="height:390px; max-width:800px; margin: 0 auto"></div>
    
    $(function () {
        $("#gridContainer").dxDataGrid({
            dataSource: books,
            customizeColumns: function (columns) {
                columns[0].width = 100
                columns[1].width = 210
            },
            paging: { pageSize: 8 }
        });
    });

    dataErrorOccurred

    Deprecated

    Use the onDataErrorOccurred option instead.

    dataSource

    Specifies a data source for the grid.

    Default Value: null

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

    • An Array of objects
      The fields of each object will be used to provide data for corresponding grid columns.

    • A DataSource or its Configuration Object
      The DataSource is a stateful object that includes options for data sorting, grouping and filtering; it also keeps data transformation options and applies them each time data is loaded. The DataSource also provides events intended to handle changing data and the state. The DataSource's underlying data access logic is isolated in a Store. Unlike the DataSource, a Store is a stateless object implementing a universal interface for reading and modifying data. To learn more, refer to the Data Layer topic.

    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 dxDataGrid 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:
    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.

    <div id="gridContainer" style="height:390px; max-width:800px; margin: 0 auto"></div>
    
    $(function () {
        $("#gridContainer").dxDataGrid({
            dataSource: [
                { author: 'D. Adams', title: "The Hitchhiker's Guide to the Galaxy", year: 1979, genre: 'Comedy, sci-fi', format: 'hardcover' },
                { author: 'K. Vonnegut', title: "Cat's Cradle", year: 1963, genre: 'Satire, sci-fi', format: 'e-book' },
                { author: 'M. Mitchell', title: "Gone with the Wind", year: 1936, genre: 'Historical fiction', format: 'hardcover' },
                { author: 'H. Lee', title: "To Kill a Mockingbird", year: 1960, genre: 'Novel', format: 'e-book' },
                { author: 'G. Orwell', title: "Nineteen Eighty-Four", year: 1949, genre: 'Dystopian novel, political fiction', format: 'hardcover' },
                { author: 'R. Bradbury', title: "The Martian Chronicles", year: 1950, genre: 'Sci-fi', format: 'e-book' },
                { author: 'K. Vonnegut', title: "God Bless You, Mr. Rosewater, or Pearls Before Swine", year: 1965, genre: 'Novel', format: 'paperback' },
                { author: 'J. D. Salinger', title: 'The Catcher in the Rye', year: 1951, genre: 'Bildungsroman', format: 'paperback' },
                { author: 'C. Dickens', title: "Great Expectations", year: 1861, genre: 'Realistic fiction', format: 'paperback' },
                { author: 'J. Austen', title: "Pride and Prejudice", year: 1813, genre: 'Novel of manners', format: 'paperback' }
            ]
        });
    });

    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:
    jQuery

    In this example, you can enable/disable the dxDataGrid 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.

    <div id="gridContainer" style="height:380px; max-width:800px; margin: 0 auto"></div>
    <div id="checkboxContainer" style="height:20px;margin:5px auto;text-align:center">
        <input type="checkbox" id="disableGridCheckbox"> Disable the Grid
    </div>
    $(function () {
        $("#gridContainer").dxDataGrid({
            dataSource: books,
            columns: [
                'author',
                { dataField: 'title', width: 210 },
                'year', 'genre', 'format'
            ],
            paging: { pageSize: 8 }
        });
    
        $('#disableGridCheckbox').change(function () {
            var dataGrid = $('#gridContainer').dxDataGrid('instance');
            dataGrid.option({
                disabled: this.checked
            });
        });
    });

    editing

    Contains options that specify how grid content can be changed.

    Type: Object

    dxDataGrid supports editing, insertion and the removing of grid values. The availability of performing a certain operation is specified by the editEnabled, insertEnabled and removeEnabled options.

    Editing in dxDataGrid can be performed in two different modes: row and batch. In the row mode, all changes made in grid rows are reflected in the data source immediately after editing completes. In the batch mode, changes are buffered before being transmitted to the data source. The user sends them manually once he or she finishes editing.

    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:
    jQuery

    In this example, you can perform all kinds of data modifications available in the dxDataGrid 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.

    <div id="gridContainer" style="height:390px; max-width:800px; margin: 0 auto"></div>
    
    $(function () {
        $("#gridContainer").dxDataGrid({
            dataSource: books,
            columns: [
                'author',
                { dataField: 'title', width: 210 },
                'year', 'genre', 'format'
            ],
            paging: { pageSize: 7 },
            editing: {
                editMode: 'batch',
                editEnabled: true,
                insertEnabled: true,
                removeEnabled: true
            }
        });
    });
    

    editingStart

    Deprecated

    Use the onEditingStart option instead.

    editorPrepared

    Deprecated

    Use the onEditorPrepared option instead.

    editorPreparing

    Deprecated

    Use the onEditorPreparing option instead.

    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.

    filterRow

    Specifies filter row options.

    Type: Object

    In dxDataGrid, 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.

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

    <div id="gridContainer" style="height:390px; max-width:800px; margin: 0 auto"></div>
    
    $(function () {
        $("#gridContainer").dxDataGrid({
            dataSource: orders,
            columns: [
                { dataField: 'OrderID', width: 100, filterOperations: [], selectedFilterOperation: '=' },
                { dataField: 'CustomerID', selectedFilterOperation: 'startswith' },
                { dataField: 'OrderDate', dataType: 'date', selectedFilterOperation: '=' },
                { dataField: 'ShippedDate', dataType: 'date', selectedFilterOperation: '=' },
                { dataField: 'ShipName', selectedFilterOperation: 'contains' },
                { dataField: 'ShipCountry', caption: 'Ship To', selectedFilterOperation: 'startswith' }
            ],
            pager: { visible: false },
            scrolling: { mode: 'infinite' },
            filterRow: {
                visible: true,
                showOperationChooser: false
            }
        });
    });

    focusStateEnabled

    Specifies whether or not the widget can be focused.

    Type: Boolean
    Default Value: false

    grouping

    Specifies the behavior of grouped grid records.

    Type: Object

    In dxDataGrid, records can be grouped by column values. The behavior of the grouped records is determined by the options of the grouping configuration object.

    A group of records can appear in a grid either extended or collapsed. To specify that, use the autoExpandAll option. Manual group collapsing can be prohibited entirely by setting the allowCollapsing option to false. Note that specifying both of these options may result in a lack of functionality. For example, when manual collapsing of groups is prohibited, but all groups are collapsed as the autoExpandAll is set to false, there is no way of expanding any group in a grid. Hence, be mindful when using both the allowCollapsing and autoExpandAll options.

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

    View Demo

    Show Example:
    jQuery

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

    <div id="gridContainer" style="height:390px; max-width:800px; margin: 0 auto"></div>
    
    $(function () {
        $("#gridContainer").dxDataGrid({
            dataSource: books,
            paging: { pageSize: 8 },
            groupPanel: { visible: true },
            grouping: { autoExpandAll: false }
        });
    });

    groupPanel

    Specifies options that configure the group panel.

    Type: Object

    Grid records in dxDataGrid can be grouped by one column or by several. Once a column is used for grouping, it is added to a group panel.

    A group panel is a grid element holding the headers of columns that grid records are grouped by. To make a group panel visible, you must set its visible option to true. When the group panel is visible, a user can drag grid columns onto and from it, thus grouping grid records. If you need to prohibit the dragging of columns to the group panel, set the allowColumnDragging option to false. In this case, columns can be added to the group panel from code only. Additionally, you can change the text displayed by the group panel when it is empty using the emptyPanelText option.

    View Demo

    Show Example:
    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.

    <div id="gridContainer" style="height:390px; max-width:800px; margin: 0 auto"></div>
    
    $(function () {
        $("#gridContainer").dxDataGrid({
            dataSource: books,
            columns: [
                'author',
                { dataField: 'title', width: 210 },
                'year', 'genre', 'language',
                { dataField: 'format', groupIndex: 0 }
            ],
            paging: { pageSize: 7 },
            groupPanel: {
                visible: true,
                allowColumnDragging: false
            }
        });
    });

    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., height:function(){ return baseHeight - 10 + "%"; })

    Show Example:
    jQuery

    In this example, you can change the height of the dxDataGrid widget using the buttons under it. These buttons increase/decrease the widget's height by 1 pixel.

    <div id="gridContainer" style="height:380px; max-width:800px; margin: 0 auto"></div>
    <div style="margin:5px;text-align:center">
        <div id="decreaseHeightButton" style="height: 40px"></div>
        <div id="increaseHeightButton" style="height: 40px"></div>
    </div>
    var initialContainerHeight = $("#gridContainer").height();
    
    var checkHeight = function () {
        var widgetHeight = $('#gridContainer').dxDataGrid('instance').option('height');
        return widgetHeight == initialContainerHeight || widgetHeight == 200;
    };
    
    $(function () {
        $("#gridContainer").dxDataGrid({
            dataSource: books,
            columns: [
                'author',
                { dataField: 'title', width: 210 },
                'year', 'genre', 'language', 'format'
            ],
            paging: { pageSize: 8 },
            height: initialContainerHeight
        });
    
        $("#decreaseHeightButton").dxButton({
            text: '-1',
            onClick: function (info) {
                var dataGrid = $('#gridContainer').dxDataGrid('instance');
                var oldHeight = dataGrid.option('height');
                dataGrid.option({
                    height: oldHeight - 1
                });
                dataGrid.repaint();
                if (checkHeight())
                    info.component.option('disabled', true);
                var increaseButton = $('#increaseHeightButton').dxButton('instance');
                if (increaseButton.option('disabled'))
                    increaseButton.option('disabled', false);
            }
        });
    
        $("#increaseHeightButton").dxButton({
            text: '+1',
            disabled: true,
            onClick: function (info) {
                var dataGrid = $('#gridContainer').dxDataGrid('instance');
                var oldHeight = dataGrid.option('height');
                dataGrid.option({
                    height: oldHeight + 1
                });
                dataGrid.repaint();
                if (checkHeight())
                    info.component.option('disabled', true);
                var decreaseButton = $('#decreaseHeightButton').dxButton('instance');
                if (decreaseButton.option('disabled'))
                    decreaseButton.option('disabled', false);
            }
        });
    });

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

    <div id="gridContainer" style="height:380px; max-width:800px; margin: 0 auto"></div>
    <div style="text-align:center">
        <div id="enableHighlightingCheckbox" style="height:25px; width:auto"></div>
    </div>
    $(function () {
        $("#gridContainer").dxDataGrid({
            dataSource: books,
            columns: [
                'author',
                { dataField: 'title', width: 210 },
                'year', 'genre', 'format'
            ],
            paging: { pageSize: 8 },
            hoverStateEnabled: true
        });
    
        $("#enableHighlightingCheckbox").dxCheckBox({
            value: true,
            text: 'Enable Row Highlighting on Hover Over',
            onValueChanged: function (info) {
                var dataGrid = $('#gridContainer').dxDataGrid('instance');
                dataGrid.option({
                    hoverStateEnabled: info.value
                });
            }
        });
    });

    initNewRow

    Deprecated

    Use the onInitNewRow option instead.

    loadPanel

    Specifies options configuring the load panel.

    Type: Object

    When dxDataGrid operates with a large number of records or uses a remote storage as a data source, loading data takes time. While data is not yet ready, dxDataGrid 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.

    Show Example:
    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.

    <div id="gridContainer" style="height: 350px; max-width: 800px; margin: 0 auto"></div>
    <div style="text-align: center; margin: 10px auto">
        <div id="buttonContainer" style="height: 40px"></div>
    </div>
    $(function () {
        $("#gridContainer").dxDataGrid({
            dataSource: {
                store: {
                    type: 'odata',
                    jsonp: true,
                    url: 'http://services.odata.org/v2/Northwind/Northwind.svc/Orders'
                }
            },
            scrolling: { mode: 'virtual' },
            columns: [
                { dataField: 'OrderID', width: 90 },
                { dataField: 'ShipName', caption: 'Name', width: 190 },
                { dataField: 'ShipCity', caption: 'City' },
                { dataField: 'ShipCountry', caption: 'Country' },
                'OrderDate',
                'RequiredDate'
            ],
            loadPanel: {
                height: 150,
                width: 400,
                text: 'Data is loading...'
            }
        });
    
        $("#buttonContainer").dxButton({
            text: 'Refresh',
            onClick: function () {
                var dataGrid = $('#gridContainer').dxDataGrid('instance');
                dataGrid.refresh();
            }
        });
    });

    masterDetail

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

    Type: Object

    In dxDataGrid, 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 dxDataGrid 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:
    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.

    <div id="gridContainer" style="height: 250px; max-width: 800px; margin: 0 auto"></div>
    <div id="noDataTextBox" style="height: 45px; width: 280px; text-align: center"></div>
    $(function () {
        $("#gridContainer").dxDataGrid({
            dataSource: undefined
        });
    
        $("#noDataTextBox").dxTextBox({
            placeholder: 'Enter a text for the empty grid',
            height: 40,
            width: 300,
            onValueChanged: function (info) {
                var dataGrid = $('#gridContainer').dxDataGrid('instance');
                dataGrid.option({
                    noDataText: info.value
                });
            }
        });
    });

    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.
    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 value of the clicked cell as it is specified in a data source.
    value: any
    The value of the clicked cell in a string format. Use this field to get the value with applied format and precision.
    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 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.
    columnIndex: Number
    The 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.
    column: Object
    The settings of the column to which the clicked cell belongs.
    rowIndex: Number
    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.
    rowType: String
    Provides access to element-related jQuery operations.
    cellElement: jQuery
    The element of the clicked cell.
    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:
    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.

    <div id="gridContainer" style="height:390px; max-width:800px; margin: 0 auto"></div>
    
    $(function () {
        $("#gridContainer").dxDataGrid({
            dataSource: employees,
            columns: [
                { dataField: 'TitleOfCourtesy', caption: 'Title' },
                'FirstName',
                'LastName',
                { dataField: 'Title', caption: 'Position', width: 150 },
                { dataField: 'BirthDate', dataType: 'date', format: 'shortDate' },
                { dataField: 'HireDate', dataType: 'date', format: 'shortDate' }
            ],
            onCellClick: function (clickedCell) {
                clickedCell.cellElement.hasClass("clicked") ? clickedCell.cellElement.removeClass("clicked") : clickedCell.cellElement.addClass("clicked")
            }
        });
    });
    .clicked {
        color: 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.
    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 value of the current cell as it is specified in the data source.
    value: any
    The value of the current cell in a string format. Use this field to get the value with an applied format and precision.
    text: 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.
    displayValue: String
    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.
    columnIndex: Number
    The 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.
    rowIndex: Number
    The settings of the column to which the current cell belongs.
    column: Object
    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.
    rowType: String
    Provides access to element-related jQuery operations.
    cellElement: jQuery
    The element of the hovered cell.
    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:
    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.

    <div id="gridContainer" style="height:390px; max-width:800px; margin: 0 auto"></div>
    
    $(function () {
        $("#gridContainer").dxDataGrid({
            dataSource: orders,
            columns: [
                'OrderID',
                { dataField: 'CustomerID', allowSorting: false },
                { dataField: 'OrderDate', dataType: 'date' },
                { dataField: 'ShippedDate', dataType: 'date' },
                { dataField: 'ShipName', allowSorting: false },
                { dataField: 'ShipCountry', caption: 'Ship To' }
            ],
            paging: { pageSize: 8 },
            onCellHoverChanged: function (hoverCell) {
                if (hoverCell.eventType == 'mouseover')
                    hoverCell.cellElement.addClass("hovered");
                else
                    hoverCell.cellElement.removeClass("hovered");
            }
        });
    });
    .hovered {
        color: forestgreen
    }
    

    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.
    data: Object
    The object of a data source represented by the row to which the prepared cell belongs.
    key: any
    The value of the prepared cell as it is specified in the data source.
    value: any
    The value of the prepared cell in a string format. Use this field to get the value with applied format and precision.
    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 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.
    columnIndex: Number
    The index of the row to which the prepared 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 prepared cell belongs.
    rowIndex: Number
    The type of the row to which the prepared cell belongs. This field equals 'data' for ordinary rows or 'group' for group rows. Use this field to distinguish rows by type.
    rowType: String
    The group index of the prepared cell. This field is useful if the rowType field is 'group'.
    groupIndex: Number
    Indicates whether or not the group cell is expanded. This field is useful if the rowType field is 'group'.
    isSelected: Boolean
    The prepared cell; provides access to element-related jQuery operations.
    isExpanded: Boolean
    Indicates whether or not the current row is expanded.
    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:
    jQuery

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

    <div id="gridContainer" style="height:390px; max-width:800px; margin: 0 auto"></div>
    
    $(function () {
        $("#gridContainer").dxDataGrid({
            dataSource: beers,
            columns: [
                'name', 'beer_style', 'alcohol_content', 'brewery_brand', 'from_region'
            ],
            paging: { pageSize: 8 },
            onCellPrepared: function (info) {
                if (info.value == "")
                    info.cellElement.addClass("noData");
            }
        });
    });
    .noData {
        background-color: cornsilk
    }

    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.
    Default Value: null

    Assign a function to perform a custom action when widget content is ready.

    Show Example:
    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.

    <div id="gridContainer" style="height:380px; max-width:800px; margin: 0 auto"></div>
    <div id="messageContainer" style="height:20px;margin:5px auto;text-align:center"></div>
    var count = 0;
    
    $(function () {
        $("#gridContainer").dxDataGrid({
            dataSource: orders,
            columns: [
                "OrderID", "CustomerID",
                { dataField: "OrderDate", dataType: 'date', format: 'shortDate' },
                { dataField: "RequiredDate", dataType: 'date', format: 'shortDate' },
                "Freight", "ShipName"
            ],
            paging: { pageSize: 6 },
            filterRow: { visible: true },
            groupPanel: { visible: true },
            selection: { mode: 'single' },
            onContentReady: function () {
                count++;
                var message = "<b>onContentReady</b> has been called for the " + count + (count < 2 ? " time" : " times");
                $('#messageContainer').html(message);
            }
        });
    });

    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.
    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.
    Default Value: null

    Assign a function to perform a custom action when you dispose of this component.

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

    <div id="gridContainer" style="height:390px; max-width:800px; margin: 0 auto"></div>
    
    $(function () {
        $("#gridContainer").dxDataGrid({
            dataSource: books,
            columns: [
                'author',
                { dataField: 'title', width: 210 },
                'year', 'genre', 'format'
            ],
            paging: { pageSize: 7 },
            editing: {
                editMode: 'batch',
                insertEnabled: true,
                editEnabled: true
            },
            onEditingStart: function (info) {
                if (info.key) {
                    info.cancel = true;
                }
            }
        });
    });

    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.
    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.
    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 dxDataGrid 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.
    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 allowing 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.
    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 dxDataGrid 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.

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

    <div id="gridContainer" style="height:390px; max-width:800px; margin: 0 auto"></div>
    
    $(function () {
        $("#gridContainer").dxDataGrid({
            dataSource: books,
            columns: [
                'author',
                { dataField: 'title', width: 210 },
                'year', 'genre', 'format'
            ],
            paging: { pageSize: 7 },
            editing: { insertEnabled: true },
            onInitNewRow: function (info) {
                info.data.format = 'paperback';
            }
        });
    });

    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.
    element: jQuery
    An HTML element of the widget.
    model: Object
    Provides access to the data that is available for binding against the element.
    value: any
    Specifies a new value for the option.
    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.
    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 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: When the clicked row is in the editing state, or switches to the editing state, the rowClick event will not fire.

    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.

    Show Example:
    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.

    <div id="gridContainer" style="height:390px; max-width:800px; margin: 0 auto"></div>
    
    $(function () {
        $("#gridContainer").dxDataGrid({
            dataSource: employees,
            columns: [
                { dataField: 'TitleOfCourtesy', caption: 'Title' },
                'FirstName',
                'LastName',
                { dataField: 'Title', caption: 'Position', width: 150 },
                { dataField: 'BirthDate', dataType: 'date', format: 'shortDate' },
                { dataField: 'HireDate', dataType: 'date', format: 'shortDate' }
            ],
            onRowClick: function (info) {
                info.rowElement.hasClass("clicked") ? info.rowElement.removeClass("clicked") : info.rowElement.addClass("clicked")
            }
        });
    });
    .clicked {
        background-color: rgba(211, 211, 211, 0.3)
    }
    

    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.
    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.
    data: Object
    Data of the row.
    cancel: Boolean
    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.

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

    <div id="gridContainer" style="height:390px; max-width:800px; margin: 0 auto"></div>
    
    $(function () {
        $("#gridContainer").dxDataGrid({
            dataSource: books,
            columns: [
                'author',
                { dataField: 'title', width: 210 },
                'year', 'genre', 'format'
            ],
            paging: { pageSize: 7 },
            editing: { insertEnabled: true },
            onRowInserting: function (info) {
                if (!info.data.author || !info.data.title) {
                    info.cancel = true;
                    alert("The \"Author\" or \"Title\" field is not specified.");
                }
            }
        });
    });

    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.
    data: Object
    The object of a data source represented by the prepared row.
    key: any
    Values of the current row as they exist in the data source.
    values: any
    The 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.
    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
    Indicates whether the prepared row is selected.
    rowType: String
    The type of the prepared 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.
    groupIndex: Number
    The prepared row; provides access to element-related jQuery operations.
    isSelected: Boolean
    Indicates whether the prepared row is selected.
    isExpanded: Boolean
    Indicates whether the prepared row is expanded.
    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:
    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.

    <div id="gridContainer" style="height:390px; max-width:800px; margin: 0 auto"></div>
    
    $(function () {
        $("#gridContainer").dxDataGrid({
            dataSource: [
                { author: 'D. Adams', title: "The Hitchhiker's Guide to the Galaxy", year: 1979, genre: 'Comedy, sci-fi', format: 'hardcover' },
                { author: 'K. Vonnegut', title: "Cat's Cradle", year: 1963, genre: 'Satire, sci-fi', format: 'e-book' },
                { author: 'M. Mitchell', title: "Gone with the Wind", year: 1936, genre: 'Historical fiction', format: 'hardcover' },
                { author: 'L. Tolstoy', title: "Anna Karenina", year: 1877, genre: 'Realist novel', format: 'hardcover' },
                { author: 'G. Orwell', title: "Nineteen Eighty-Four", year: 1949, genre: 'Dystopian novel, political fiction', format: 'hardcover' },
                { author: 'R. Bradbury', title: "The Martian Chronicles", year: 1950, genre: 'Sci-fi', format: 'e-book' },
                { author: 'J. D. Salinger', title: 'The Catcher in the Rye', year: 1951, genre: 'Bildungsroman', format: 'paperback' },
                { author: 'C. Dickens', title: "Great Expectations", year: 1861, genre: 'Realistic fiction', format: 'paperback' },
                { author: 'E. Hemingway', title: "For Whom the Bell Tolls", year: 1940, genre: 'War novel', format: 'e-book' },
                { author: 'J. Austen', title: "Pride and Prejudice", year: 1813, genre: 'Novel of manners', format: 'paperback' }
            ],
            columns: [
                'author',
                { dataField: 'title', width: 250 },
                'year', 'genre', 'format'
            ],
            onRowPrepared: function (info) {
                if (info.data.year > 1800 && info.data.year <= 1900)
                    info.rowElement.addClass("nineteenthCentury");
            }
        });
    });
    .nineteenthCentury {
        color: silver
    }

    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.
    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.
    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.
    cancel: Boolean
    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.

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

    <div id="gridContainer" style="height:390px; max-width:800px; margin: 0 auto"></div>
    
    $(function () {
        $("#gridContainer").dxDataGrid({
            dataSource: books,
            columns: [
                'author',
                { dataField: 'title', width: 210 },
                'year', 'genre', 'format'
            ],
            paging: { pageSize: 8 },
            editing: {
                removeEnabled: true,
                editMode: 'batch'
            },
            onRowRemoving: function (info) {
                if (info.data.format == 'hardcover') {
                    info.cancel = true
                }
            }
        });
    });

    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.
    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.
    oldData: Object
    Old data of the row.
    newData: Object
    Updated 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.
    cancel: Boolean
    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.

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

    <div id="gridContainer" style="height:390px; max-width:800px; margin: 0 auto"></div>
    
    $(function () {
        $("#gridContainer").dxDataGrid({
            dataSource: books,
            columns: [
                'author',
                { dataField: 'title', width: 210 },
                'year', 'genre', 'format'
            ],
            paging: { pageSize: 8 },
            editing: {
                editMode: 'batch',
                editEnabled: true
            },
            onRowUpdating: function (info) {
                if (info.oldData.format == 'hardcover') {
                    info.cancel = true;
                }
            }
        });
    });

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

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

    Show Example:
    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.

    <div id="gridContainer" style="height:390px; max-width:800px; margin: 0 auto"></div>
    
    $(function () {
        $("#gridContainer").dxDataGrid({
            dataSource: books,
            columns: [
                'author',
                { dataField: 'title', width: 210 },
                'year', 'genre', 'format'
            ],
            paging: { pageSize: 8 },
            pager: {
                showPageSizeSelector: true,
                allowedPageSizes: [3, 5, 8]
            }
        });
    });

    paging

    Specifies paging options.

    Type: Object

    In dxDataGrid, 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:
    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.

    <div id="gridContainer" style="height:390px; max-width:800px; margin: 0 auto"></div>
    
    $(function () {
        $("#gridContainer").dxDataGrid({
            dataSource: {
                store: {
                    type: 'odata',
                    jsonp: true,
                    url: 'http://services.odata.org/v2/Northwind/Northwind.svc/Orders'
                }
            },
            columns: [
                { dataField: 'OrderID', width: 90 },
                { dataField: 'ShipName', caption: 'Name', width: 190 },
                { dataField: 'ShipCity', caption: 'City' },
                { dataField: 'ShipCountry', caption: 'Country' },
                'OrderDate',
                'RequiredDate'
            ],
            paging: {
                pageSize: 8,
                pageIndex: 19
            }
        });
    });

    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 on the client-side using the remoteOperations option.

    By default, this option is set to 'auto'. It means that whether operations are performed on the client or on the server side depends on the type of the data source. The use of an array of objects, an ArrayStore or a LocalStore forces dxDataGrid to perform filtering, sorting and paging locally. If you use an ODataStore or a CustomStore, these operations are performed remotely.

    To control individual operations, set the filtering, paging and sorting fields of the remoteOperations object. To control all operations together, assign a boolean value directly to the remoteOperations option.

    NOTE: Certain grid features, such as summary or expanding/collapsing all groups at once, are available only if the grid operates with local data.

    NOTE: When setting this option to false or assigning an object with field(s) set to false, corresponding operations are performed locally, but they are accompanied by loading data from the remote server. This is required to use actual data when performing these operations locally.

    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:
    jQuery

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

    <div id="gridContainer" style="height:380px; max-width:800px; margin: 0 auto"></div>
    <div id="checkboxContainer" style="height:20px;margin:5px auto;text-align:center">
        <input type="checkbox" id="rowAlternationCheckbox" checked> Enable Row Alternation
    </div>
    $(function () {
        $("#gridContainer").dxDataGrid({
            dataSource: orders,
            columns: [
                "OrderID",
                { dataField: "OrderDate", dataType: 'date', format: 'shortDate' },
                { dataField: "ShippedDate", dataType: 'date', format: 'shortDate' },
                "Freight", "ShipName", "ShipCity"
            ],
            paging: { pageSize: 8 },
            rowAlternationEnabled: true
        });
    
        $('#rowAlternationCheckbox').change(function () {
            var dataGrid = $('#gridContainer').dxDataGrid('instance');
            dataGrid.option({
                rowAlternationEnabled: this.checked
            });
        });
    });

    rowClick

    Deprecated

    Use the onRowClick option instead.

    rowInserted

    Deprecated

    Use the onRowInserted option instead.

    rowInserting

    Deprecated

    Use the onRowInserting option instead.

    rowPrepared

    Deprecated

    Use the onRowPrepared option instead.

    rowRemoved

    Deprecated

    Use the onRowRemoved option instead.

    rowRemoving

    Deprecated

    Use the onRowRemoving option instead.

    rowTemplate

    Specifies a custom template for grid rows.

    Type: String|function(rowElement, rowInfo)|DOM Node|jQuery
    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 dxDataGrid 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'.

    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 and grouping 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.

    See Also

    View Demo

    rowUpdated

    Deprecated

    Use the onRowUpdated option instead.

    rowUpdating

    Deprecated

    Use the onRowUpdating option instead.

    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:
    jQuery

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

    <div id="gridContainer" style="height:380px; max-width:800px; margin: 0 auto"></div>
    <div style="text-align:center">
        <div id="checkboxContainer" style="height:25px; width:auto"></div>
    </div>
    $(function () {
        $("#gridContainer").dxDataGrid({
            dataSource: books,
            columns: [
                'author',
                { dataField: 'title', width: 210 },
                'year', 'genre', 'format'
            ],
            paging: { pageSize: 8 },
            rtlEnabled: false
        });
    
        $("#checkboxContainer").dxCheckBox({
            value: false,
            text: 'Enable the Right-To-Left Representation',
            onValueChanged: function (info) {
                var dataGrid = $('#gridContainer').dxDataGrid('instance');
                dataGrid.option({
                    rtlEnabled: info.value
                });
            }
        });
    });

    scrolling

    A configuration object specifying scrolling options.

    Type: Object

    The dxDataGrid 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:
    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.

    <div id="gridContainer" style="height:390px; max-width:800px; margin: 0 auto"></div>
    
    $(function () {
        var scrollingModes = ['standard', 'virtual', 'infinite'];
    
        $("#gridContainer").dxDataGrid({
            dataSource: {
                store: {
                    type: 'odata',
                    jsonp: true,
                    url: 'http://services.odata.org/v2/Northwind/Northwind.svc/Orders'
                }
            },
            columns: [
                { dataField: 'OrderID', width: 90 },
                { dataField: 'ShipName', caption: 'Name', width: 190 },
                { dataField: 'ShipCity', caption: 'City' },
                { dataField: 'ShipCountry', caption: 'Country' },
                'OrderDate',
                'RequiredDate'
            ],
            scrolling: { mode: 'infinite' }
        });
    });

    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 dxDataGrid 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:
    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.

    <div id="gridContainer" style="height:390px; max-width:800px; margin: 0 auto"></div>
    
    $(function () {
        $("#gridContainer").dxDataGrid({
            dataSource: orders,
            columns: [
                'OrderID', 'CustomerID',
                { dataField: 'OrderDate', dataType: 'date' },
                { dataField: 'ShippedDate', dataType: 'date' },
                'ShipName',
                { dataField: 'ShipCountry', caption: 'Ship To' }
            ],
            paging: { pageSize: 7 },
            searchPanel: {
                visible: true,
                width: 250
            }
        });
    });

    selectedRowKeys

    Specifies the keys of the records that must appear selected initially.

    Type: Array

    Apart from runtime selection, the dxDataGrid 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 a data source (see the example below). If no key was specified, the whole data object is considered the key.

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

    Show Example:
    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.

    <div id="gridContainer" style="height:390px; max-width:800px; margin: 0 auto"></div>
    
    var booksArray = [
        { bookID: 1, author: 'D. Adams', title: "The Hitchhiker's Guide to the Galaxy", year: 1979, genre: 'Comedy, sci-fi', format: 'hardcover' },
        { bookID: 2, author: 'K. Vonnegut', title: "Cat's Cradle", year: 1963, genre: 'Satire, sci-fi', format: 'e-book' },
        { bookID: 3, author: 'M. Mitchell', title: "Gone with the Wind", year: 1936, genre: 'Historical fiction', format: 'hardcover' },
        { bookID: 4, author: 'H. Lee', title: "To Kill a Mockingbird", year: 1960, genre: 'Novel', format: 'e-book' },
        { bookID: 5, author: 'G. Orwell', title: "Nineteen Eighty-Four", year: 1949, genre: 'Dystopian novel, political fiction', format: 'hardcover' },
        { bookID: 6, author: 'R. Bradbury', title: "The Martian Chronicles", year: 1950, genre: 'Sci-fi', format: 'e-book' },
        { bookID: 7, author: 'K. Vonnegut', title: "God Bless You, Mr. Rosewater, or Pearls Before Swine", year: 1965, genre: 'Novel', format: 'paperback' },
        { bookID: 8, author: 'J. D. Salinger', title: 'The Catcher in the Rye', year: 1951, genre: 'Bildungsroman', format: 'paperback' },
        { bookID: 9, author: 'C. Dickens', title: "Great Expectations", year: 1861, genre: 'Realistic fiction', format: 'paperback' },
        { bookID: 10, author: 'J. Austen', title: "Pride and Prejudice", year: 1813, genre: 'Novel of manners', format: 'paperback' }
    ];
    
    $(function () {
        $("#gridContainer").dxDataGrid({
            dataSource: {
                store: {
                    data: booksArray,
                    type: 'array',
                    key: 'bookID'
                }
            },
            columns: [
                'author',
                { dataField: 'title', width: 220 },
                { dataField: 'year', width: 50 },
                'genre', 'format'
            ],
            selectedRowKeys: [1, 5, 8],
            selection: { mode: 'multiple' }
        });
    });

    selection

    Specifies options of runtime selection.

    Type: Object

    dxDataGrid 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

    For a structured overview of dxDataGrid selection capabilities, see the Selection article.

    View Demo

    Show Example:
    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.

    <div id="gridContainer" style="height:390px; max-width:800px; margin: 0 auto"></div>
    
    var selectionModes = ['none', 'single', 'multiple'];
    
    $(function () {
        $("#gridContainer").dxDataGrid({
            dataSource: books,
            columns: [
                'author',
                { dataField: 'title', width: 210 },
                'year', 'genre', 'format'
            ],
            paging: { pageSize: 8 },
            selection: {
                mode: 'multiple',
                allowSelectAll: false
            }
        });
    });

    selectionChanged

    Deprecated

    Use the onSelectionChanged option instead.

    showBorders

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

    Type: Boolean
    Default Value: false

    Show Example:
    jQuery

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

    <div id="gridContainer" style="height:370px; max-width:800px; margin: 0 auto"></div>
    <div style="text-align:center">
        <div id="showBordersCheckbox" style="height:25px; width:auto"></div>
    </div>
    $(function () {
        $("#gridContainer").dxDataGrid({
            dataSource: employees,
            columns: [
                { dataField: 'TitleOfCourtesy', caption: 'Title' },
                'FirstName',
                'LastName',
                { dataField: 'Title', caption: 'Position', width: 150 },
                { dataField: 'BirthDate', dataType: 'date', format: 'shortDate' },
                { dataField: 'HireDate', dataType: 'date', format: 'shortDate' }
            ],
            paging: { enabled: false },
            showBorders: false
        });
    
        $("#showBordersCheckbox").dxCheckBox({
            value: false,
            text: 'Show Grid Borders',
            onValueChanged: function (info) {
                var dataGrid = $('#gridContainer').dxDataGrid('instance');
                dataGrid.option({
                    showBorders: info.value
                });
            }
        });
    });

    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:
    jQuery

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

    <div id="gridContainer" style="height:360px; max-width:800px; margin: 0 auto"></div>
    <div style="text-align:center">
        <div id="showColumnHeadersCheckbox" style="height:25px; width:auto"></div>
    </div>
    $(function () {
        $("#gridContainer").dxDataGrid({
            dataSource: employees,
            columns: [
                { dataField: 'TitleOfCourtesy', caption: 'Title' },
                'FirstName',
                'LastName',
                { dataField: 'Title', caption: 'Position', width: 150 },
                { dataField: 'BirthDate', dataType: 'date', format: 'shortDate' },
                { dataField: 'HireDate', dataType: 'date', format: 'shortDate' }
            ],
            paging: { pageSize: 8 },
            showColumnHeaders: true
        });
    
        $("#showColumnHeadersCheckbox").dxCheckBox({
            value: true,
            text: 'Show Column Headers',
            onValueChanged: function (info) {
                var dataGrid = $('#gridContainer').dxDataGrid('instance');
                dataGrid.option({
                    showColumnHeaders: info.value
                });
            }
        });
    });

    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 native look for the widget. In case you still require the column lines to be displayed, choose another theme.

    View Demo

    Show Example:
    jQuery

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

    <div id="gridContainer" style="height:360px; max-width:800px; margin: 0 auto"></div>
    <div style="text-align:center">
        <div id="showColumnLinesCheckbox" style="height:25px; width:auto"></div>
    </div>
    $(function () {
        $("#gridContainer").dxDataGrid({
            dataSource: employees,
            columns: [
                { dataField: 'TitleOfCourtesy', caption: 'Title' },
                'FirstName',
                'LastName',
                { dataField: 'Title', caption: 'Position', width: 150 },
                { dataField: 'BirthDate', dataType: 'date', format: 'shortDate' },
                { dataField: 'HireDate', dataType: 'date', format: 'shortDate' }
            ],
            paging: { pageSize: 8 },
            showColumnLines: true
        });
    
        $("#showColumnLinesCheckbox").dxCheckBox({
            value: true,
            text: 'Show Column Lines',
            onValueChanged: function (info) {
                var dataGrid = $('#gridContainer').dxDataGrid('instance');
                dataGrid.option({
                    showColumnLines: info.value
                });
            }
        });
    });

    showRowLines

    Specifies whether or not horizontal lines separating one grid row from another are visible.

    Type: Boolean
    Default Value: false
    Show Example:
    jQuery

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

    <div id="gridContainer" style="height:360px; max-width:800px; margin: 0 auto"></div>
    <div style="text-align:center">
        <div id="showRowLinesCheckbox" style="height:25px; width:auto"></div>
    </div>
    $(function () {
        $("#gridContainer").dxDataGrid({
            dataSource: books,
            columns: [
                'author',
                { dataField: 'title', width: 210 },
                'year', 'genre', 'language', 'format'
            ],
            paging: { pageSize: 8 },
            showRowLines: true
        });
    
        $("#showRowLinesCheckbox").dxCheckBox({
            value: true,
            text: 'Show Row Lines',
            onValueChanged: function (info) {
                var dataGrid = $('#gridContainer').dxDataGrid('instance');
                dataGrid.option({
                    showRowLines: info.value
                });
            }
        });
    });

    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 dxDataGrid, 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

    For a structured overview of dxDataGrid sorting capabilities, see the Sorting article.

    View Demo

    Show Example:
    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.

    <div id="gridContainer" style="height:390px; max-width:800px; margin: 0 auto"></div>
    
    $(function () {
        $("#gridContainer").dxDataGrid({
            dataSource: books,
            columns: [
                'author',
                { dataField: 'title', width: 210 },
                'year', 'genre', 'format'
            ],
            paging: { pageSize: 8 },
            sorting: { mode: 'multiple' }
        });
    });

    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.

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

    dxDataGrid 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 dxDataGrid: 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

    visible

    A Boolean value specifying whether or not the widget is visible.

    Type: Boolean
    Default Value: true

    Show Example:
    jQuery

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

    <div id="gridContainer" style="height:360px; max-width:800px; margin: 0 auto"></div>
    <div style="text-align:center">
        <div id="showWidgetCheckbox" style="height:25px; width:auto"></div>
    </div>
    $(function () {
        $("#gridContainer").dxDataGrid({
            dataSource: books,
            columns: [
                'author',
                { dataField: 'title', width: 210 },
                'year', 'genre', 'language', 'format'
            ],
            paging: { pageSize: 8 }
        });
    
        $("#showWidgetCheckbox").dxCheckBox({
            value: true,
            text: 'Show dxDataGrid',
            onValueChanged: function (info) {
                var dataGrid = $('#gridContainer').dxDataGrid('instance');
                dataGrid.option({
                    visible: info.value
                });
            }
        });
    });

    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:
    jQuery

    In this example, you can change the width of the dxDataGrid widget using the buttons under it. These buttons increase/decrease the widget's width by 1 pixel.

    <div id="gridContainer" style="height:360px; max-width:800px; margin: 0 auto"></div>
    <div style="margin:5px;text-align:center">
        <div id="decreaseWidthButton" style="height: 40px"></div>
        <div id="increaseWidthButton" style="height: 40px"></div>
    </div>
    var initialContainerWidth = $("#gridContainer").width();
    
    var checkWidth = function () {
        var widgetWidth = $('#gridContainer').dxDataGrid('instance').option('width');
        return widgetWidth == initialContainerWidth || widgetWidth == 200;
    };
    
    $(function () {
        $("#gridContainer").dxDataGrid({
            dataSource: books,
            columns: [
                'author',
                { dataField: 'title', width: 210 },
                'year', 'genre', 'language', 'format'
            ],
            paging: { pageSize: 8 },
            width: initialContainerWidth
        });
    
        $("#decreaseWidthButton").dxButton({
            text: '-1',
            onClick: function (info) {
                var dataGrid = $('#gridContainer').dxDataGrid('instance');
                var oldWidth = dataGrid.option('width');
                dataGrid.option({
                    width: oldWidth - 1
                });
                dataGrid.repaint();
                if (checkWidth())
                    info.component.option('disabled', true);
                var increaseButton = $('#increaseWidthButton').dxButton('instance');
                if (increaseButton.option('disabled'))
                    increaseButton.option('disabled', false);
            }
        });
    
        $("#increaseWidthButton").dxButton({
            text: '+1',
            disabled: true,
            onClick: function (info) {
                var dataGrid = $('#gridContainer').dxDataGrid('instance');
                var oldWidth = dataGrid.option('width');
                dataGrid.option({
                    width: oldWidth + 1
                });
                dataGrid.repaint();
                if (checkWidth())
                    info.component.option('disabled', true);
                var decreaseButton = $('#decreaseWidthButton').dxButton('instance');
                if (decreaseButton.option('disabled'))
                    decreaseButton.option('disabled', false);
            }
        });
    });

    wordWrapEnabled

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

    Type: Boolean
    Default Value: false

    Show Example:
    jQuery

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

    <div id="gridContainer" style="height:380px; max-width:800px; margin: 0 auto"></div>
    <div style="text-align:center">
        <div id="wordWrapEnabledCheckbox" style="height:25px; width:auto"></div>
    </div>
    $(function () {
        $("#gridContainer").dxDataGrid({
            dataSource: books,
            columns: [
                'author',
                { dataField: 'title', width: 210 },
                'year', 'genre', 'language', 'format'
            ],
            paging: { pageSize: 8 },
            wordWrapEnabled: true
        });
    
        $("#wordWrapEnabledCheckbox").dxCheckBox({
            value: true,
            text: 'Enable Word Wrap',
            onValueChanged: function (info) {
                var dataGrid = $('#gridContainer').dxDataGrid('instance');
                dataGrid.option({
                    wordWrapEnabled: info.value
                });
            }
        });
    });