React DataGrid - columns

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

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

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

View Demo Watch Video

See Also

• Column Types
• Customize Column Headers
• Column Sizing
• Column Reordering
• Column Fixing
• Hide a Column Using the API
• Adaptability
• Column and Row Indexes

The default alignment of the content depends on the type of data.

Use the HorizontalAlignment enum to specify this option when the widget is used as an ASP.NET MVC Control. This enum accepts the following values: Left, Center, and Right.

See Also

• editing

See Also

• export

See Also

• columns[].allowHeaderFiltering

See Also

• columnFixing
• columns[].fixed

When grouping is enabled in the widget, the user can group data by values of any column. To prohibit a particular column from being used for grouping, set the allowGrouping option of this column to false.

See Also

• Grouping

See Also

• columnChooser

See Also

• columns[].width
• columnAutoWidth
• columnMinWidth

See Also

• sorting

See Also

• Expand and Collapse Groups - API
• Expand and Collapse Groups - User Interaction

Column cells contain values from the data field by default, but you can populate them with custom values instead. For this, declare the calculateCellValue function that is called each time a new row is rendered.

Certain features are disabled in a column with calculated values by default. The following list specifies these features and how you can enable them:

$(function() {
    $("#dataGridContainer").dxDataGrid({
        columns: [{
            calculateCellValue: function(rowData) {
                // ...
                return this.defaultCalculateCellValue(rowData);
            }
        }]
    });
});

import { DxDataGridModule } from "devextreme-angular";
// ...
export class AppComponent {
    calculateCellValue (rowData) {
        // ...
        let column = this as any;
        return column.defaultCalculateCellValue(rowData);

    }
}
@NgModule({
    imports: [
        // ...
        DxDataGridModule
    ],
    // ...
})

<dx-data-grid ... >
    <dxi-column [calculateCellValue]="calculateCellValue" ... ></dxi-column>
</dx-data-grid>

See Also

• columns[].calculateDisplayValue

This option accepts the name of the data source field that provides display values...

$(function() {
    $("#datagridContainer").dxdatagrid({
        columns: [{
            dataField: "countryID", // provides values for editing
            calculateDisplayValue: "country" // provides display values
        }]
    });
});

<dx-datagrid ... >
    <dxi-column
        dataField="countryID" <!-- provides values for editing -->
        calculateDisplayValue="country"> <!-- provides display values -->
    </dxi-column>
</dx-datagrid>

import { DxdatagridModule } from "devextreme-angular";
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxdatagridModule
    ],
    // ...
})

@(Html.DevExtreme().datagrid()
    .Columns(columns => columns.Add()
        .DataField("CountryID")
        .CalculateDisplayValue("Country")
    )
)

@(Html.DevExtreme().datagrid() _
    .Columns(Sub(columns)
        columns.Add() _
            .DataField("CountryID") _
            .CalculateDisplayValue("Country")
    End Sub)        
)

... or a function that combines display values. Specify this function only if all data processing operations are executed on the client.

$(function() {
    $("#datagridContainer").dxdatagrid({
        columns: [{
            dataField: "countryID", // provides values for editing
            calculateDisplayValue: function (rowData) { // combines display values
                return rowData.capital + " (" + rowData.country + ")";
            }
        }]
    });
});

<dx-datagrid ... >
    <dxi-column
        dataField="countryID" <!-- provides values for editing -->
        [calculateDisplayValue]="getCountryWithCapital"> <!-- combines display values -->
    </dxi-column>
</dx-datagrid>

import { DxdatagridModule } from "devextreme-angular";
// ...
export class AppComponent {
    getCountryWithCapital(rowData) {
        return rowData.capital + " (" + rowData.country + ")";
    }
}
@NgModule({
    imports: [
        // ...
        DxdatagridModule
    ],
    // ...
})

@(Html.DevExtreme().datagrid()
    .Columns(columns => columns.Add()
        .DataField("CountryID")
        .CalculateDisplayValue(new JS("getCountryWithCapital"))
    )
)

<script>
    function getCountryWithCapital(rowData) {
        return rowData.capital + " (" + rowData.country + ")";
    }        
</script>

@(Html.DevExtreme().datagrid() _
    .Columns(Sub(columns)
        columns.Add() _
            .DataField("CountryID") _
            .CalculateDisplayValue(New JS("getCountryWithCapital"))
    End Sub)        
)

<script>
    function getCountryWithCapital(rowData) {
        return rowData.capital + " (" + rowData.country + ")";
    }        
</script>    

The widget uses the specified display values in sorting, searching, and grouping (in case of DataGrid).

Do not use this option to format text in cells. Instead, use the format, customizeText, or cellTemplate option.

This function must return a filter expression. The simplest filter expression has the following format:

[selector, selectedFilterOperation, filterValue]

• selector
  A data source field or a function providing actual column values. Pass this.calculateCellValue if your column contains calculated values.

• selectedFilterOperation
  A comparison operator. One of the following: "=", "<>", ">", ">=", "<", "<=", "between", "startswith", "endswith", "contains", "notcontains".

  NOTE

  For the "between" operator, the returned filter expression has a slightly different format: [[selector, ">=", startValue], "and", [selector, "<=", endValue]].

• filterValue
  A user input value. Values the selector provides are compared to this value.

In the following code, the calculateFilterExpression function implements an exclusive between operation. This is done by overriding the default inclusive implementation.

$(function() {
    $("#datagridContainer").dxdatagrid({
        // ...
        columns: [{
            calculateFilterExpression: function (filterValue, selectedFilterOperation) {
                // Implementation for the "between" comparison operator
                if (selectedFilterOperation === "between" && $.isArray(filterValue)) {
                    var filterExpression = [
                        [this.dataField, ">", filterValue[0]], 
                        "and", 
                        [this.dataField, "<", filterValue[1]]
                    ];
                    return filterExpression;
                }
                // Invokes the default filtering behavior
                return this.defaultCalculateFilterExpression.apply(this, arguments);
            },
            // ...
        }]
    });
});

import { DxdatagridModule } from "devextreme-angular";
// ...
export class AppComponent {
    calculateFilterExpression (filterValue, selectedFilterOperation) {
        let column = this as any;
        // Implementation for the "between" comparison operator
        if (selectedFilterOperation === "between" && Array.isArray(filterValue)) {
            var filterExpression = [
                [column.dataField, ">", filterValue[0]], 
                "and", 
                [column.dataField, "<", filterValue[1]]
            ];
            return filterExpression;
        }
        // Invokes the default filtering behavior
        return column.defaultCalculateFilterExpression(arguments);
    }
}
@NgModule({
    imports: [
        // ...
        DxdatagridModule
    ],
    // ...
})

<dx-datagrid ... >
    <dxi-column [calculateFilterExpression]="calculateFilterExpression" ... ></dxi-column>
</dx-datagrid>

In the previous code, the defaultCalculateFilterExpression function invokes the default behavior. You can omit the function call if you do not need it.

By default, grouping is conducted using the exact values that the grouping column contains. However, in some cases, this approach may be giving poor results, e.g., when a user tries to group records by a column that contains dates. In such cases, it may be preferable to use calculated values in grouping. For this purpose, assign a function to the calculateGroupValue option. This function must return the calculated value for grouping.

This option accepts the name of the data source field that provides values to be used in sorting...

$(function() {
    $("#datagridContainer").dxdatagrid({
        columns: [{
            dataField: "Position", // provides values for the column
            calculateSortValue: "isOnVacation" // provides values to be used in sorting 
        }]
    });
});

<dx-datagrid ... >
    <dxi-column
        dataField="Position" <!--provides values for the column -->
        calculateSortValue="isOnVacation"> <!-- provides values to be used in sorting -->
    </dxi-column>
</dx-datagrid>

import { DxdatagridModule } from "devextreme-angular";
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxdatagridModule
    ],
    // ...
})

... or a function that returns such a value.

$(function() {
    var datagrid = $("#datagridContainer").dxdatagrid({
        columns: [{
            dataField: "Position",
            sortOrder: "asc",
            calculateSortValue: function (rowData) {
                if (rowData.Position == "CEO")
                    return datagrid.columnOption("Position", "sortOrder") == "asc" ? "aaa" : "zzz"; // CEOs are always displayed at the top
                else
                    return rowData.Position; // Others are sorted as usual
            }
        }]
    }).dxdatagrid("instance");
});

import { DxdatagridModule } from "devextreme-angular";
// ...
export class AppComponent {
    customSortingFunction (rowData) {
        let column = this as any;
        if (rowData.Position == "CEO")
            return column.sortOrder == "asc" ? "aaa" : "zzz"; // CEOs are always displayed at the top
        else
            return rowData.Position; // Others are sorted as usual
    }
}
@NgModule({
    imports: [
        // ...
        DxdatagridModule
    ],
    // ...
})

<dx-datagrid ... >
    <dxi-column
        dataField="Position"
        sortOrder="asc"
        [calculateSortValue]="customSortingFunction">
    </dxi-column>
</dx-datagrid>

See Also

• sortingMethod

Use this option to display a descriptive or friendly name for the column. If this option is not set, the caption will be generated from the name of the dataField.

The cellInfo object has the following fields:

• data: Object
  The data of the row to which the cell belongs.
• component: Object
  The widget's instance.
• value: Any
  The value of the cell as it is specified in the data source.
• displayValue: Any
  The display value of the cell. Differs from the value field only when the column uses lookup or calculateDisplayValue.
• text: String
  displayValue after applying format and customizeText.
• columnIndex: Number
  The index of the column to which the cell belongs. For more information on how this index is calculated, refer to the Column and Row Indexes topic.
• rowIndex: Number
  The index of the row to which the cell belongs. Begins with 0 on each page. Group rows are included. For details on row indexes, see the Column and Row Indexes topic.
• column: Object
  The settings of the column to which the cell belongs.
• rowType: String
  The row's type.

View Function Template Demo View Underscore Template Demo

See Also

• Customize Cells Appearance
• Custom Templates
• onCellPrepared

Unlike normal columns, band columns do not hold data. Instead, they collect two or more columns under one column header. To set up this layout, declare the band column using a hierarchical structure. For this, assign the nested columns to the columns field of the band column. For example, the following code declares the "Address" band column and nests three columns within it.

$(function() {
    $("#datagridContainer").dxdatagrid({
        // ...
        columns: [{
            caption: "Address",
            columns: ["City", "Street", "Apartment"]
        }, {
            // ...
        }]
    });
});

<dx-datagrid ... >
    <dxi-column caption="Address">
        <dxi-column dataField="City"></dxi-column>
        <dxi-column dataField="Street"></dxi-column>
        <dxi-column dataField="Apartment"></dxi-column>
    </dxi-column>
</dx-datagrid>

import { DxdatagridModule } from "devextreme-angular";
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxdatagridModule
    ],
    // ...
})

A nested column has almost every option a regular column has. These options are described in the columns section of the Reference.

For example, the following code specifies the width and sortOrder options of the "Street" column nested within the fixed "Address" band column.

$(function() {
    $("#datagridContainer").dxdatagrid({
        // ...
        columns: [{
            caption: "Address",
            fixed: true,
            fixedPosition: "right",
            columns: [
                "City", {
                    dataField: "Street",
                    width: 100,
                    sortOrder: "asc"
                },
                "Apartment"
            ]
        }, {
            // ...
        }]
    });
});

<dx-datagrid ... >
    <dxi-column
        caption="Address"
        [fixed]="true"
        fixedPosition="right">
        <dxi-column dataField="City"></dxi-column>
        <dxi-column dataField="Street" [width]="100" sortOrder="asc"></dxi-column>
        <dxi-column dataField="Apartment"></dxi-column>
    </dxi-column>
</dx-datagrid>

import { DxdatagridModule } from "devextreme-angular";
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxdatagridModule
    ],
    // ...
})

Band columns support hierarchies of any nesting level. It means that the following structure is acceptable.

$(function() {
    $("#datagridContainer").dxdatagrid({
        // ...
        columns: [{
            caption: "A",
            columns: [ "A1", "A2", {
                caption: "A3",
                columns: ["A31", "A32", {
                    caption: "A33",
                    columns: ["A331", "A332", "A333"]
                }]
            }]
        }, {
            caption: "B",
            columns: // ...
        }]
    });
});

<dx-datagrid ... >
    <dxi-column caption="A">
        <dxi-column dataField="A1"></dxi-column>
        <dxi-column dataField="A2"></dxi-column>
        <dxi-column caption="A3">
            <dxi-column dataField="A31"></dxi-column>
            <dxi-column dataField="A32"></dxi-column>
            <dxi-column caption="A33">
                <dxi-column dataField="A331"></dxi-column>
                <dxi-column dataField="A332"></dxi-column>
                <dxi-column dataField="A333"></dxi-column>
            </dxi-column>
        </dxi-column>
    </dxi-column>
    <dxi-column caption="B">
        ...
    </dxi-column>
</dx-datagrid>

import { DxdatagridModule } from "devextreme-angular";
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxdatagridModule
    ],
    // ...
})

Band columns have the isBand flag. Banded columns have the ownerBand option set. Use these options to distinguish band and banded columns from regular ones in code.

See Also

• Band Columns
• Column Fixing

The customizeText function can be called to highlight the matching text correctly when the data displayed in the column matches the search condition.

See Also

• Customize the Value and Text
• columns[].calculateCellValue

The columns array can contain only the names of data source fields, which is sufficient if you do not need to specify any other column options. But if you do, then this array should contain objects that configure columns. To bind the columns to data source fields, use the dataField option. Note that you can combine both declarations in a single array as shown in the following code.

$(function() {
    $("#datagridContainer").dxdatagrid({
        // ...
        columns: [
            "CustomerID",
            { dataField: "EmployeeID", width: 200 },
            "OrderDate",
            { dataField: "Freight", format: "fixedPoint" },
            "ShipName",
            "ShipCity"
        ]
    });
});

<dx-datagrid ... >
    <dxi-column dataField="CustomerID"></dxi-column>
    <dxi-column dataField="EmployeeID" [width]="200"></dxi-column>
    <dxi-column dataField="OrderDate"></dxi-column>
    <dxi-column dataField="Freight" format="fixedPoint"></dxi-column>
    <dxi-column dataField="ShipName"></dxi-column>
    <dxi-column dataField="ShipCity"></dxi-column>
</dx-datagrid>

import { DxdatagridModule } from "devextreme-angular";
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxdatagridModule
    ],
    // ...
})

See Also

• Columns - Overview

If a data field provides values of one data type, but the widget should cast them to another, specify the proper type in this option. In the following code, values of the ID and hireDate fields are cast to numeric and date data types, respectively.

$(function() {
    $("#datagrid").dxdatagrid({
        // ...
        dataSource: [{
            ID: "1",
            hireDate: 1491821760000
        }, // ...
        ],
        columns: [{
            dataField: "ID",
            dataType: "number"
        }, {
            dataField: "hireDate",
            dataType: "date"
        }]
    });
})

<dx-datagrid ...
    [dataSource]="employees">
    <dxi-column
        dataField="ID"
        dataType="number">
    </dxi-column>
    <dxi-column 
        dataField="hireDate"
        dataType="date">
    </dxi-column>
</dx-datagrid>

import { DxdatagridModule } from 'devextreme-angular';
// ...
export class AppComponent {
    employees = [{
        ID: "1",
        hireDate: 1491821760000
    }, // ...
    ];
}
@NgModule({
    imports: [
        // ...
        DxdatagridModule 
    ],
    // ...
})

@(Html.DevExtreme().datagrid()
    .DataSource(new JS("employees"))
    .Columns(c => {
        c.Add()
            .DataField("ID")
            .DataType(GridColumnDataType.Number);
        c.Add()
            .DataField("hireDate")
            .DataType(GridColumnDataType.Date);
    })
)
<script>
    var employees = [{
        ID: "1",
        hireDate: 1491821760000
    }, // ...
    ];
</script>

<template>
    <dx-datagrid ...
        :data-source="employees">
    <dx-column
        data-field="ID"
        data-type="number"
    />
    <dx-column
        data-field="hireDate"
        data-type="date"
    />
    </dx-datagrid>
</template>
<script>
import { Dxdatagrid, DxColumn } from 'devextreme-vue/datagrid';

const employees = [{
    ID: '1',
    hireDate: 1491821760000
}, // ...
];

export default {
    components: {
        Dxdatagrid,
        DxColumn
    },
    data() {
        employees
    }
};
</script>

import React from 'react';
import { datagrid, Column } from 'devextreme-react/datagrid';

const employees = [{
    ID: '1',
    hireDate: 1491821760000
}, // ...
];

class App extends React.Component {
    render() {
        return (
            <datagrid ...
                dataSource={employees}>
                <Column dataField="ID" dataType="number" />
                <Column dataField="hireDate" dataType="date" />
            </datagrid>
        );
    }
}
export default App;

Use the GridColumnDataType enum to specify this option when the widget is used as an ASP.NET MVC Control. This enum accepts the following values: String, Number, Date, DateTime, Boolean, and Object.

See Also

• Data Columns

The cellInfo object has the following fields:

• setValue(newValue, newText): Method
  A method that you should call to change the cell value and, optionally, the displayed value after the editor's value is changed.

  NOTE

  In batch editing mode, check that the value changed before calling this method to ensure correct cell highlighting.

• data: Object
  The data of the row the cell belongs to.

• component: Object
  The widget's instance.
• value: Any
  The cell value as it is specified in the data source.
• displayValue: Any
  The displayed cell value. Differs from the value field only when the column uses lookup or calculateDisplayValue.
• text: String
  displayValue after applying format and customizeText.
• columnIndex: Number
  The index of the column the cell belongs to. Refer to the Column and Row Indexes topic for more information on how this index is calculated.
• rowIndex: Number
  The index of the row the cell belongs to. Begins with 0 on each page. Group rows are included. Refer to the Column and Row Indexes topic for more information on row indexes.
• column: Object
  The settings of the column the cell belong to.
• rowType: String
  The row's type.

See Also

• Customize Editors
• Custom Templates

Depending on the dataType, the column offers a user different widgets for editing and filtering (using the filter row): TextBox, DateBox, Lookup, etc. In the editorOptions object, you can specify options for the widget.

$(function() {
    $("#datagridContainer").dxdatagrid({
        // ...
        onEditorPreparing: function(e) {
            if (e.dataField == "requiredDataField") {
                var standardHandler = e.editorOptions.onValueChanged;
                e.editorOptions.onValueChanged = function(e) { // Overriding the standard handler
                    // ...
                    // Custom commands go here
                    // ...
                    standardHandler(e); // Calling the standard handler to save the edited value
                }
            }
        }
    });
});

import { DxdatagridModule } from "devextreme-angular";
// ...
export class AppComponent {
    onEditorPreparing (e) {
        if (e.dataField == "requiredDataField") {
            let standardHandler = e.editorOptions.onValueChanged;
            e.editorOptions.onValueChanged = function (e) { // Overriding the standard handler
                // ...
                // Custom commands go here
                // ...
                standardHandler(e); // Calling the standard handler to save the edited value
            }
        }
    }
}
@NgModule({
    imports: [
        // ...
        DxdatagridModule
    ],
    // ...
})

<dx-data-grid ... 
    (onEditorPreparing)="onEditorPreparing($event)">
</dx-data-grid>

When true, HTML tags are displayed as plain text; when false, they are applied to the values of the column.

See Also

• columns[].trueText

The following table lists available filters by data types. The same filters are assigned to columns of a specific data type by default.

The filterOperations option can also accept an empty array. In this case, the selected filter operation is "=" for all data types, and a user cannot change it.

Use the FilterOperations enum to specify this option when the widget is used as an ASP.NET MVC Control. This enum accepts the following values: Equal, NotEqual, LessThan, LessThanOrEqual, GreaterThan, GreaterThanOrEqual, NotContains, Contains, StartsWith, EndsWith, and Between.

See Also

• columns[].selectedFilterOperation
• columns[].filterValue

This option accepts the following values.

• include
  Values in the header filter are unselected initially, and the user changes the filter by selecting, that is, including the values.
• exclude
  All values in the header filter are selected initially, and the user changes the filter by clearing the selection of certain values, that is, by excluding them.

Use the FilterType enum to specify this option when the widget is used as an ASP.NET MVC Control. This enum accepts the following values: Include and Exclude.

See Also

• Filtering API
• columns[].filterValues

This value is applied using the selectedFilterOperation.

If the headerFilter.groupInterval option is set, each value in the filterValues array specifies the beginning of an interval instead of an exact value:

$(function() {
    $("datagridContainer").dxdatagrid({
        // ...
        columns: [{
            dataField: "ID",
            dataType: "number",
            headerFilter: { groupInterval: 100 },
            filterValues: [500, 700], // Filter intervals are 500-600 and 700-800
        },
        // ...
        ]
    })
});

import { DxdatagridModule } from "devextreme-angular";
// ...
export class AppComponent {
    columns = [{
        dataField: "ID",
        dataType: "number",
        headerFilter: { groupInterval: 100 },
        filterValues: [500, 700], // Filter intervals are 500-600 and 700-800
    },
    // ...
    ];
}
@NgModule({
    imports: [
        // ...
        DxdatagridModule
    ],
    // ...
})

<dx-datagrid ...
    [columns]="columns">
</dx-datagrid>

See Also

• Filtering - Header Filter

See Also

• columnFixing
• columns[].fixedPosition

Use the HorizontalEdge enum to specify this option when the widget is used as an ASP.NET MVC Control. This enum accepts the following values: Left and Right.

See Also

• columnFixing

This option also controls the user input in cells that use the DateBox widget for editing. For cells that use other widgets, you can specify the editorOptions.format option.

$(function(){
    $("#datagridContainer").dxdatagrid({
        dataSource: orders,
        editing: {
            allowUpdating: true
        },
        columns: [{
            dataField: "SaleAmount",
            format: "currency",
            editorOptions: {
                format: "$ #,##0.##"
            }
        }, 
        // ...
        ]
    });
});

<dx-datagrid
    [dataSource]="orders">
    <dxo-editing [allowUpdating]="true"></dxo-editing>
    <dxi-column
        dataField="SaleAmount"
        format="currency"
        [editorOptions]="{ format: '$ #,##0.##' }">
    </dxi-column>
</dx-datagrid>

See Also

• format

In the following code, the Full_Name grid column in the editing state produces a form item that spans two form columns. The item's label is on top of the editor:

$(function() {
    $("#datagridContainer").dxdatagrid({
        // ...
        editing: {
            allowUpdating: true,
            mode: "form"
        },
        columns: [{
            dataField: "Full_Name",
            formItem: {
                colSpan: 2,
                label: {
                    location: "top"
                }
            }
        },
        // ...
        ]
    });
});

<dx-datagrid ... >
    <dxo-editing
        [allowUpdating]="true"
        mode="form">
    </dxo-editing>
    <dxi-column dataField="Full_Name">
        <dxo-form-item [colSpan]="2">
            <dxo-label location="top"></dxo-label>
        </dxo-form-item>
    </dxi-column>
</dx-datagrid>

import { DxdatagridModule } from "devextreme-angular";
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxdatagridModule
    ],
    // ...
})

@(Html.DevExtreme().datagrid()
    // ...
    .Editing(e => e
        .AllowUpdating(true)
        .Mode(GridEditMode.Form)
    )
    .Columns(cols => {
        // ...
        cols.Add().DataField("Full_Name")
            .FormItem(item => item
                .ColSpan(2)
                .Label(l => l.Location(FormLabelLocation.Top)
            )
        );
    })
)

See Also

• Form Edit Mode

The cellInfo object has the following fields:

• data
  Contains a data object that represents data items matching a grouping key. For example, if you group grid records by country, the following object can be obtained from the data field.

  JavaScript

  {
      key: "Spain", // The name of a country
      items: [      // Data source objects corresponding to the key
          { ... }, 
          { ... },
          // ...
      ]
  }

• component
  Contains the DataGrid instance.
• value
  Contains the value of the current group cell as it is specified in a data source.
• text
  Contains the value of the current group cell in a string format. Use this field to get a value with applied format.
• displayValue
  Contains the value displayed by the current group cell. Differs from the value field only when the column to which the current cell belongs uses lookup.
• columnIndex
  Contains the index of the column to which the current group cell belongs. For more information on how this index is calculated, refer to the Column and Row Indexes topic.
• rowIndex
  Contains the index of the row that the current group cell occupies. For further information about row indexes, see the Column and Row Indexes topic.
• column
  Contains the settings of the column to which the current group cell belongs.
• summaryItems
  An array of group summary items that are defined to be displayed in a group row. The array objects have the structure of the group summary items with an addition of the value (the summary item value) and columnCaption (usually used to present a summary value) fields.
• groupContinuesMessage
  If the current group continues on the next page, this field contains a corresponding message. The value of this field equals the value of the grouping.groupContinuesMessage property. If the current group does not continue on the next page, this field equals undefined.
• groupContinuedMessage
  If the current group is continued from the previous page, this field contains a corresponding message. The value of this field equals the value of the grouping.groupContinuedMessage property. If the current group is not continued from the previous page, this field equals undefined.

See Also

• Custom Templates
• Default Templates

At runtime, the user can group grid records using the context menu or the group panel. But there may be cases when grid records must be grouped initially. To do this, assign an integer value to the groupIndex option of those columns that should be used for grouping grid records. For example, consider the following data source.

var dataSource = [
    { FirstName: "John", LastName: "Doe", Title: "Sales Manager" },
    { FirstName: "Michael", LastName: "King", Title: "Sales Representative" },
    // ...
];

To group these records first by the "LastName" field and then by the "FirstName" field, use the following code.

$("#dataGridContainer").dxDataGrid({
    // ...
    columns: [
        { dataField: "FirstName", groupIndex: 1 },
        { dataField: "LastName", groupIndex: 0 },
        // ...
    ]
});

<dx-data-grid ... >
    <dxi-column dataField="FirstName" [groupIndex]="1"></dxi-column>
    <dxi-column dataField="LastName" [groupIndex]="0"></dxi-column>
</dx-data-grid>

import { DxDataGridModule } from "devextreme-angular";
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxDataGridModule
    ],
    // ...
})

View Demo

See Also

-Initial and Runtime Grouping

The headerInfo object has the following fields:

• component: Object
  The widget's instance.
• columnIndex: Number
  The index of the column to which the header belongs. For details on how this index is calculated, refer to the Column and Row Indexes topic.
• column: Object
  The settings of the column to which the header belongs.

See Also

• Custom Templates

See Also

• headerFilter

The hidingPriority is a unique positive integer that ascends from right to left beginning with 0 by default. Columns with low hidingPriority are hidden first.

See Also

• columnHidingEnabled
• onAdaptiveDetailRowPreparing
• Adaptability

Unlike normal columns, band columns do not hold data. Instead, they collect two or more columns under one column header. In most cases, to set up this layout, you can declare the band column using a hierarchical structure. For example, the following code bands three columns under the "Address" header.

$(function() {
    $("#datagridContainer").dxdatagrid({
        // ...
        columns: [{
            caption: "Address",
            columns: ["City", "Street", "Apartment"]
        }, {
            // ...
        }]
    });
});

<dx-datagrid ... >
    <dxi-column caption="Address">
        <dxi-column dataField="City"></dxi-column>
        <dxi-column dataField="Street"></dxi-column>
        <dxi-column dataField="Apartment"></dxi-column>
    </dxi-column>
</dx-datagrid>

import { DxdatagridModule } from "devextreme-angular";
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxdatagridModule
    ],
    // ...
})

If you use the customizeColumns option to configure columns, the hierarchical structure cannot be implemented. To band columns in this case, use the isBand and ownerBand options.

$(function() {
    $("#datagridContainer").dxdatagrid({
        // ...
        customizeColumns: function(columns) {
            columns.push({ // Pushes the "Address" band column into the "columns" array
                caption: "Address",
                isBand: true
            });

            var addressFields = ["City", "Street", "Apartment"];
            for (var i = 0; i < columns.length-1; i++) {
                if (addressFields.indexOf(columns[i].dataField) > -1) // If the column belongs to "Address",
                    columns[i].ownerBand = columns.length-1; // assigns "Address" as the owner band column
            }
        }
    });
});

import { DxdatagridModule } from "devextreme-angular";
// ...
export class AppComponent {
    customizeColumns (columns) {
        columns.push({ // Pushes the "Address" band column into the "columns" array
            caption: "Address",
            isBand: true
        });

        let addressFields = ["City", "Street", "Apartment"];
        for (let i = 0; i < columns.length - 1; i++) {
            if (addressFields.indexOf(columns[i].dataField) > -1) // If the column belongs to "Address",
                columns[i].ownerBand = columns.length - 1; // assigns "Address" as the owner band column
        }
    }
}
@NgModule({
    imports: [
        // ...
        DxdatagridModule
    ],
    // ...
})

<dx-datagrid ...
    [customizeColumns]="customizeColumns">
</dx-datagrid>

Band columns can have the following properties only:

• alignment
• allowHiding
• allowReordering
• caption
• columns
• cssClass
• fixed
• fixedPosition
• headerCellTemplate
• name
• ownerBand
• showInColumnChooser
• visible
• visibleIndex

See Also

• Band Columns

A lookup column restricts the set of values that can be chosen when a user edits or filters the column. In a lookup column, each cell is a drop-down menu. You can use a lookup column when you need to substitute displayed values with required values. For example, consider that you have two arrays of objects: drivers and buses.

var drivers = [
    { driverID: 1, firstName: "John", lastName: "Smith", busID: 2 },
    { driverID: 2, firstName: "Lizzy", lastName: "Cook", busID: 1 },
    { driverID: 3, firstName: "Brian", lastName: "Hawkins", busID: 3 }
];

var buses = [
    { busID: 1, plates: "123456" },
    { busID: 2, plates: "AB-1234" },
    { busID: 3, plates: "CD-9876" }
];

All drivers have the busID field, which refers to a bus. If drivers is the main dataSource, the Bus ID column displays bus IDs, which provides little information to a user. It will be more useful to display bus license plates instead of IDs. For this, the buses array must be set as a lookup dataSource for the Bus ID column. Then, the names of data fields must be assigned to the valueExpr and displayExpr options. Values from the valueExpr data field will be replaced with values from the displayExpr data field.

$(function() {
    $("#dataGridContainer").dxDataGrid({
        dataSource: drivers,
        // ...
        columns: [{
            dataField: "busID",
            lookup: {
                dataSource: buses,
                valueExpr: "busID",
                displayExpr: "plates"
            }
        }]
    });
});

<dx-data-grid [dataSource]="drivers">
    <dxi-column dataField="busID">
        <dxo-lookup
            [dataSource]="buses"
            valueExpr="busID"
            displayExpr="plates">
        </dxo-lookup>
    </dxi-column>
</dx-data-grid>

import { DxDataGridModule } from "devextreme-angular";
// ...
export class AppComponent {
    drivers = [
        { driverID: 1, firstName: "John", lastName: "Smith", busID: 2 },
        { driverID: 2, firstName: "Lizzy", lastName: "Cook", busID: 1 },
        { driverID: 3, firstName: "Brian", lastName: "Hawkins", busID: 3 }
    ];
    buses = [
        { busID: 1, plates: "123456" },
        { busID: 2, plates: "AB-1234" },
        { busID: 3, plates: "CD-9876" }
    ];
}
@NgModule({
    imports: [
        // ...
        DxDataGridModule
    ],
    // ...
})

With this code, the Bus ID column contains license plates instead of IDs. Moreover, the user can choose a plate number from the drop-down menu when editing cells or applying a filter to this column.

View Demo

See Also

• Bind a Lookup Column to a Custom Data Source
• Customize Editors
• Enhance Performance on Large Datasets - Lookup Optimization

See Also

• columnMinWidth
• allowColumnResizing

Set this option if you need to refer to the column in your code afterwards, for example, when changing a column option.

Main article: isBand

See Also

• renderAsync

The following table lists default filter operations by data type:

Use the FilterOperations enum to specify this option when the widget is used as an ASP.NET MVC Control. This enum accepts the following values: Equal, NotEqual, LessThan, LessThanOrEqual, GreaterThan, GreaterThanOrEqual, NotContains, Contains, StartsWith, EndsWith, and Between.

See Also

• Filtering API

Using this function, you can process user input before it is saved to the data source. This function accepts the newData, value and currentRowData parameters. value is the user input that you should assign to one of the fields of the newData. Initially, newData is an empty object. Fill it with fields whose values should be saved in the data object of the current row. currentRowData is a read-only parameter used to access the current row data.

$(function() {
    $("#datagridContainer").dxdatagrid({
        // ...
        columns: [
            "Price",
            {
                dataField: "Count",
                dataType: "number",
                setCellValue: function(newData, value, currentRowData) {
                    newData.Count = value;
                    newData.TotalPrice = currentRowData.Price * value;
                }
            },
            "TotalPrice",
            // ...
        ]
    });
});

import { DxdatagridModule } from "devextreme-angular";
// ...
export class AppComponent {
    setCellValue (newData, value, currentRowData) {
        newData.Count = value;
        newData.TotalPrice = currentRowData.Price * value;
    }
}
@NgModule({
    imports: [
        // ...
        DxdatagridModule
    ],
    // ...
})

<dx-datagrid ... >
    <dxi-column dataField="Price"></dxi-column>
    <dxi-column
        dataField="Count"
        dataType="number"
        [setCellValue]="setCellValue">
    </dxi-column>
    <dxi-column dataField="TotalPrice"></dxi-column>
</dx-datagrid>

To invoke the default behavior, call the this.defaultSetCellValue(newData, value) function.

A column cell has normal and editing states. In a normal state, the cell value is text. In the editing state, the cell contains an editor that indicates the cell value and allows a user to edit it. In certain cases, a viewer reads the cell value easier if it is indicated by an editor even in the normal state. For example, boolean values are more comprehensible when they are indicated by check boxes. To display editors in cells permanently, set the showEditorAlways option to true.

See Also

• columns[].editorOptions

See Also

• columns[].visible

Displaying a grouping column may be useful if you calculate its grouping values. Consider that you need to group records by a column that contains dates. Grouping by full dates seems inconvenient. It would be smarter to group by months or years instead. For this purpose, you calculate grouping values within the calculateGroupValue function and leave the grouping column visible by setting the showWhenGrouped option to true so that the user can view the full dates.

This option accepts an integer specifying the index of the column in a collection of columns with applied sorting. For example, consider the following data source that can provide data for three columns.

var dataSource = [
    { firstName: "John", lastName: "Doe", title: "Sales Manager" },
    { firstName: "Michael", lastName: "King", title: "Sales Representative" },
    // ...
];

To sort data first by the "Last Name" and then by the "First Name" column, use the following code. Note that the sortOrder option should also be specified.

$(function() {
    $("#datagridContainer").dxdatagrid({
        // ...
        columns: [
            { dataField: "firstName", sortIndex: 1, sortOrder: "asc" },
            { dataField: "lastName", sortIndex: 0, sortOrder: "asc" },
            // ...
        ]
    });
});

<dx-datagrid ... >
    <dxi-column dataField="firstName" [sortIndex]="1" sortOrder="asc"></dxi-column>
    <dxi-column dataField="lastName" [sortIndex]="0" sortOrder="asc"></dxi-column>
</dx-datagrid>

import { DxdatagridModule } from "devextreme-angular";
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxdatagridModule
    ],
    // ...
})

You can set the sortIndex option at design time to specify initial sorting, or change this option using the columnOption method to sort at runtime.

This function accepts two cell values and should return a number indicating their sort order:

• Less than zero
  value1 goes before value2.
• Zero
  value1 and value2 remain unchanged relative to each other.
• Greater than zero
  value1 goes after value2.

The string comparison is culture-insensitive by default. Use the following code to make it culture-sensitive:

$(function () {
    $("#datagridContainer").dxdatagrid({
        // ...
        columns: [{
            dataField: "fieldName",
            sortingMethod: function (value1, value2) {
                // Handling null values
                if(!value1 && value2) return -1;
                if(!value1 && !value2) return 0;
                if(value1 && !value2) return 1;
                // Determines whether two strings are equivalent in the current locale
                return value1.localeCompare(value2);
            }
        }]
    });
});

import { DxdatagridModule } from "devextreme-angular";
// ...
export class AppComponent {
    sortStringsConsideringCulture (value1, value2) {
        // Handling null values
        if(!value1 && value2) return -1;
        if(!value1 && !value2) return 0;
        if(value1 && !value2) return 1;
        // Determines whether two strings are equivalent in the current locale
        return value1.localeCompare(value2);
    }
}
@NgModule({
    imports: [
        // ...
        DxdatagridModule
    ],
    // ...
})

<dx-datagrid ... >
    <dxi-column
        dataField="fieldName"
        [sortingMethod]="sortStringsConsideringCulture">
    </dxi-column>
</dx-datagrid>

By default, rows are sorted according to the data source. Set the sortOrder option to sort rows in a required order. If you need to sort by multiple columns, specify the sortIndex option as well, or otherwise, each sorted column will get a sort index according to the position in the columns array.

Use the SortOrder enum to specify this option when the widget is used as an ASP.NET MVC Control. This enum accepts the following values: Asc and Desc.

See Also

• sorting

See Also

• columns[].falseText

View Demo

See Also

• Data Validation
• rowValidating

See Also

• Reordering: Data Columns | Command Columns

The option supports the following types of values:

• Number
  The column's width in pixels.

• String
  A CSS-accepted column width measurement (for example, "55px", "80%" and "auto").

  NOTE

  Fixed columns ignore widths specified as a percentage.

See Also

• columnAutoWidth
• width