Angular TreeList - columns

Configures columns.

Selector: dxi-column
Type:

Array<TreeList Column | String>

Default Value: undefined
Raised Events: onOptionChanged

This property accepts an array of objects, where each object configures a single column. If a column does not need to be customized, this array may include the name of the field that provides data for this column.

jQuery
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        columns: [{
            dataField: "Title",
            caption: "Position"
        }, {
            dataField: "FullName",
            width: 300
        }, 
            "CompanyName",
            "City"
        ]
    });
});
Angular
HTML
TypeScript
<dx-tree-list ... >
    <dxi-column dataField="Title" caption="Position"></dxi-column>
    <dxi-column dataField="FullName" [width]="300"></dxi-column>
    <dxi-column dataField="CompanyName"></dxi-column>
    <dxi-column dataField="City"></dxi-column>
</dx-tree-list>
import { DxTreeListModule } from "devextreme-angular";
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})
Vue
App.vue
<template>
    <DxTreeList ... >
        <DxColumn
            data-field="Title"
            caption="Position"
        />
        <DxColumn
            data-field="FullName"
            :width="300"
        />
        <DxColumn
            data-field="CompanyName"
        />
        <DxColumn
            data-field="City"
        />
    </DxTreeList>
</template>

<script>
import 'devextreme/dist/css/dx.light.css';

import DxTreeList, {
    DxColumn
} from 'devextreme-vue/tree-list';

export default {
    components: {
        DxTreeList,
        DxColumn
    },
    // ...
}
</script>
React
App.js
import 'devextreme/dist/css/dx.light.css';

import TreeList, {
    Column
} from 'devextreme-react/tree-list';

export default function App() {
    return (
        <TreeList>
            <Column
                dataField="Title"
                caption="Position"
            />
            <Column
                dataField="FullName"
                width={300}
            />
            <Column
                dataField="CompanyName"
            />
            <Column
                dataField="City"
            />
        </TreeList>
    );
}

View Demo

See Also

alignment

Aligns the content of the column.

Type:

HorizontalAlignment

| undefined
Default Value: undefined
Accepted Values: undefined

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

dataType alignment
'number' 'right'
'boolean' 'center'
'string' 'left'
'date' 'left'
'datetime' 'left'

allowEditing

Specifies whether a user can edit values in the column at runtime. By default, inherits the value of the editing.allowUpdating property.

Type:

Boolean

Default Value: true

View Demo

NOTE
If values in the column are calculated customarily using the calculateCellValue property, they cannot be edited at runtime.
See Also

allowFiltering

Specifies whether data can be filtered by this column. Applies only if filterRow.visible is true.

Type:

Boolean

Default Value: true

See Also

allowFixing

Specifies whether a user can fix the column at runtime. Applies only if columnFixing.enabled is true.

Type:

Boolean

Default Value: true

See Also

allowHeaderFiltering

Specifies whether the header filter can be used to filter data by this column. Applies only if headerFilter.visible is true. By default, inherits the value of the allowFiltering property.

Type:

Boolean

Default Value: true

allowHiding

Specifies whether a user can hide the column using the column chooser at runtime. Applies only if columnChooser.enabled is true.

Type:

Boolean

Default Value: true, false (command column)

View Demo

NOTE
Fixed columns ignore the hidingPriority and allowHiding properties.
See Also

allowReordering

Specifies whether users can reorder this column. Overrides the allowColumnReordering property value.

Type:

Boolean

Default Value: true

View Demo

allowResizing

Specifies whether a user can resize the column at runtime. Applies only if allowColumnResizing is true.

Type:

Boolean

Default Value: true

See Also

allowSearch

Specifies whether this column can be searched. Applies only if searchPanel.visible is true. Inherits the value of the allowFiltering property by default.

Type:

Boolean

Default Value: true

allowSorting

Specifies whether a user can sort rows by this column at runtime. Applies only if sorting.mode differs from "none".

Type:

Boolean

Default Value: true

NOTE
In a column with calculated values, this property is set to false by default.
See Also

buttons[]

Allows you to customize buttons in the edit column or create a custom command column. Applies only if the column's type is "buttons".

Selector: dxi-button
Type:

Array<TreeListPredefinedColumnButton | Column Button>

View Demo

See Also

calculateCellValue

Calculates custom cell values. Use this function to create an unbound data column.

Type:

Function

Function parameters:
rowData:

Object

The data of the row to which the cell belongs.

Context: GridBaseColumn

The this keyword refers to the column's configuration.

Return Value: any

A cell's custom value.

Unlike data columns bound to a data field, unbound columns display custom values returned from the calculateCellValue function. The component executes this function multiple times for each record: when records are rendered, when users sort or filter them, and when summaries are computed. To avoid errors and enhance the UI component performance, make sure that properties of the rowData object used in calculation exist and keep calculations inside this function as simple as possible.

In the following code, the calculateCellValue function is used to create an unbound column that displays a calculated sales amount. Data objects contain the Price and UnitsSold fields used in the calculation:

jQuery
index.js
var products = [{
    ProductID: 1,
    ProductName: "Fabrikam SLR Camera 35\" X358 Blue",
    Price: 168,
    UnitsSold: 4
},
// ...
];

$(function() {
    $("#treeListContainer").dxTreeList({
        dataSource: products,
        columns: [{
            caption: "Sales Amount",
            calculateCellValue: function(rowData) {
                return rowData.Price * rowData.UnitsSold;
            }
        },
        // ...
        ]
    });
});
Angular
app.component.html
app.component.ts
app.service.ts
app.module.ts
<dx-tree-list
    [dataSource]="products">
    <dxi-column
        caption="Sales Amount"
        [calculateCellValue]="calculateSalesAmount">
    </dxi-column>
</dx-tree-list>
import { Component } from '@angular/core';
import { Product, Service } from './app.service';

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css']
})
export class AppComponent {
    products: Product[];
    constructor(service: Service) {
        this.products = service.getProducts();
    }

    calculateSalesAmount(rowData) {
        return rowData.Price * rowData.UnitsSold;
    }
}
import { Injectable } from '@angular/core';

export class Product {
    ProductID: number,
    ProductName: string,
    Price: number,
    UnitsSold: number
}

let products: Product[] = [{
    ProductID: 1,
    ProductName: "Fabrikam SLR Camera 35\" X358 Blue",
    Price: 168,
    UnitsSold: 4
},
// ...
];

@Injectable()
export class Service {
    getProducts(): Product[] {
        return products;
    }
}
import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';

import { DxTreeListModule } from 'devextreme-angular';
import { Service } from './app.service';

@NgModule({
    declarations: [
        AppComponent
    ],
    imports: [
        BrowserModule,
        DxTreeListModule
    ],
    providers: [
        Service
    ],
    bootstrap: [AppComponent]
})
export class AppModule { }
Vue
App.vue
data.js
<template>
    <DxTreeList
        :data-source="products">
        <DxColumn
            caption="Sales Amount"
            :calculate-cell-value="calculateSalesAmount">
        </DxColumn>
    </DxTreeList>
</template>

<script>
import 'devextreme/dist/css/dx.light.css';

import DxTreeList, {
    DxColumn
} from 'devextreme-vue/tree-list';

import service from './data.js';

export default {
    components: {
        DxTreeList,
        DxColumn
    },
    data() {
        const products = service.getProducts();
        return {
            products
        }
    },
    methods: {
        calculateSalesAmount(rowData) {
            return rowData.Price * rowData.UnitsSold;
        }
    }
}
</script>
const products = [{
    ProductID: 1,
    ProductName: "Fabrikam SLR Camera 35\" X358 Blue",
    Price: 168,
    UnitsSold: 4
},
// ...
];

export default {
    getProducts() {
        return products;
    }
};
React
App.js
data.js
import React from 'react';

import 'devextreme/dist/css/dx.light.css';

import TreeList, {
    Column 
} from 'devextreme-react/tree-list';

import service from './data.js';

class App extends React.Component {
    constructor(props) {
        super(props);
        this.products = service.getProducts();
    }

    calculateSalesAmount(rowData) {
        return rowData.Price * rowData.UnitsSold;
    }

    render() {
        return (
            <TreeList
                dataSource={this.products}>
                <Column
                    caption="Sales Amount"
                    calculateCellValue={this.calculateSalesAmount}
                />
            </TreeList>
        );
    }
}
export default App;
const products = [{
    ProductID: 1,
    ProductName: "Fabrikam SLR Camera 35\" X358 Blue",
    Price: 168,
    UnitsSold: 4
},
// ...
];

export default {
    getProducts() {
        return products;
    }
};

The following features are disabled in an unbound column, but you can enable them as described in this table:

Feature Action that enables it
Editing Implement the setCellValue function and specify the name property instead of dataField.
Sorting Set the allowSorting property to true.
Filtering Set the allowFiltering property to true.
Searching Set the allowSearch property to true.
Grouping (DataGrid only) Set the allowGrouping property to true.

To invoke the default behavior, call the defaultCalculateCellValue function and return its result.

jQuery
index.js
$(function() {
    $("#treeListContainer").dxTreeList({
        columns: [{
            calculateCellValue: function(rowData) {
                // ...
                return this.defaultCalculateCellValue(rowData);
            }
        }]
    });
});
Angular
app.component.ts
app.component.html
import { Component } from '@angular/core';

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css']
})
export class AppComponent {
    calculateCellValue(rowData) {
        // ...
        const column = this as any;
        return column.defaultCalculateCellValue(rowData);
    }
}
<dx-tree-list ... >
    <dxi-column ...
        [calculateCellValue]="calculateCellValue">
    </dxi-column>
</dx-tree-list>
Vue
App.vue
<template>
    <DxTreeList ... >
        <DxColumn ...
            :calculate-cell-value="calculateCellValue">
        </DxColumn>
    </DxTreeList>
</template>

<script>
// ...
export default {
    // ...
    data() {
        return {
            calculateCellValue: function(rowData) {
                // ...
                const column = this as any;
                return column.defaultCalculateCellValue(rowData);
            }
        }
    }
}
</script>
React
App.js
// ...
class App extends React.Component {
    calculateCellValue(rowData) {
        // ...
        const column = this as any;
        return column.defaultCalculateCellValue(rowData);
    }

    render() {
        return (
            <TreeList ... >
                <Column ...
                    calculateCellValue={this.calculateCellValue}
                />
            </TreeList>
        );
    }
}
export default App;
NOTE
The this keyword refers to the column's configuration.
See Also

calculateDisplayValue

Calculates custom display values for column cells. Requires specifying the dataField or calculateCellValue property. Used in lookup optimization.

Type:

String

|

Function

Function parameters:
rowData:

Object

The data of the row to which the cell belongs.

Context: GridBaseColumn

The this keyword refers to the column's configuration.

Return Value: any

The value for the cell to display.

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

jQuery
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        columns: [{
            dataField: "countryID", // provides values for editing
            calculateDisplayValue: "country" // provides display values
        }]
    });
});
Angular
HTML
TypeScript
<dx-tree-list ... >
    <dxi-column
        dataField="countryID" <!-- provides values for editing -->
        calculateDisplayValue="country"> <!-- provides display values -->
    </dxi-column>
</dx-tree-list>
import { DxTreeListModule } from "devextreme-angular";
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})
Vue
App.vue
<template>
    <DxTreeList>
        <DxColumn          
            data-field="countryID" <!-- provides values for editing -->
            calculate-display-value="country"> <!-- provides display values -->  
        />
    </DxTreeList>
</template>

<script>
import 'devextreme/dist/css/dx.light.css';

import DxTreeList, {
    DxColumn 
} from 'devextreme-vue/tree-list';

export default {
    components: {
        DxTreeList,
        DxColumn 
    },
    // ...
}
</script>
React
App.js
import React from 'react';

import 'devextreme/dist/css/dx.light.css';

import TreeList, {
    Column
} from 'devextreme-react/tree-list';

class App extends React.Component {
    // ...

    render() {
        return (
            <TreeList>
                <Column 
                    dataField="countryID"  <!-- provides values for editing -->
                    calculateDisplayValue="country"  <!-- provides display values -->  
                />
            </TreeList>
        );
    }
}
export default App;
ASP.NET MVC Controls
Razor C#
Razor VB
@(Html.DevExtreme().TreeList()
    .Columns(columns => columns.Add()
        .DataField("CountryID")
        .CalculateDisplayValue("Country")
    )
)
@(Html.DevExtreme().TreeList() _
    .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.

jQuery
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        columns: [{
            dataField: "countryID", // provides values for editing
            calculateDisplayValue: function (rowData) { // combines display values
                return rowData.capital + " (" + rowData.country + ")";
            }
        }]
    });
});
Angular
HTML
TypeScript
<dx-tree-list ... >
    <dxi-column
        dataField="countryID" <!-- provides values for editing -->
        [calculateDisplayValue]="getCountryWithCapital"> <!-- combines display values -->
    </dxi-column>
</dx-tree-list>
import { DxTreeListModule } from "devextreme-angular";
// ...
export class AppComponent {
    getCountryWithCapital(rowData) {
        return rowData.capital + " (" + rowData.country + ")";
    }
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})
Vue
App.vue
<template>
    <DxTreeList>
        <DxColumn       
            data-field="countryID" <!-- provides values for editing -->
            :calculate-display-value="getCountryWithCapital" <!-- combines display values -->
        />
    </DxTreeList>
</template>

<script>
import 'devextreme/dist/css/dx.light.css';

import DxTreeList, {
    DxColumn 
} from 'devextreme-vue/tree-list';

export default {
    components: {
        DxTreeList,
        DxColumn 
    },
    methods: {
        getCountryWithCapital(rowData) {
            return rowData.capital + " (" + rowData.country + ")";
        }
    }
}
</script>
React
App.js
import React from 'react';

import 'devextreme/dist/css/dx.light.css';

import TreeList, {
    Column
} from 'devextreme-react/tree-list';

class App extends React.Component {
    // ...

    render() {
        return (
            <TreeList>
                <Column
                    dataField="countryID" <!-- provides values for editing -->                 
                    calculateDisplayValue={this.getCountryWithCapital} <!-- combines display values -->
                />
            </TreeList>
        );
    }

    getCountryWithCapital(rowData) {
        return rowData.capital + " (" + rowData.country + ")";
    }
}
export default App;
ASP.NET MVC Controls
Razor C#
Razor VB
@(Html.DevExtreme().TreeList()
    .Columns(columns => columns.Add()
        .DataField("CountryID")
        .CalculateDisplayValue(new JS("getCountryWithCapital"))
    )
)

<script>
    function getCountryWithCapital(rowData) {
        return rowData.capital + " (" + rowData.country + ")";
    }        
</script>
@(Html.DevExtreme().TreeList() _
    .Columns(Sub(columns)
        columns.Add() _
            .DataField("CountryID") _
            .CalculateDisplayValue(New JS("getCountryWithCapital"))
    End Sub)        
)

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

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

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

calculateFilterExpression

Specifies the column's custom rules to filter data.

Type:

Function

Function parameters:
filterValue: any

A user input value.
Contains an array if the selectedFilterOperation is one of the following: "between", "anyof", "noneof".

selectedFilterOperation:

String

| null

A selected filter operation.

target:

String

A UI element used to filter data.
Possible values: "filterRow", "headerFilter", "filterBuilder", "search".

Context: GridBaseColumn

The this keyword refers to the column's configuration.

Return Value:

Filter Expression

A filter expression.

The calculateFilterExpression function should return a filter expression. A basic filter expression has the following format:

[selector, comparisonOperator, filterValue]

  • selector
    A dataField or function that returns column values. Pass this.calculateCellValue if your column contains calculated values.

  • comparisonOperator
    One of the following operators: "=", "<>", ">", ">=", "<", "<=", "startswith", "endswith", "contains", "notcontains".

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

A filter expression for the "between" operation has a different format:

[ [selector, ">=", startValue], "and", [selector, "<=", endValue] ]

The default "between" implementation is inclusive (filter results include the boundary values). In the following code, the calculateFilterExpression function implements an exclusive "between" operation:

jQuery
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        columns: [{
            calculateFilterExpression: function (filterValue, selectedFilterOperation, target) {
                // Override implementation for the "between" filter operation
                if (selectedFilterOperation === "between" && $.isArray(filterValue)) {
                    const filterExpression = [
                        [this.dataField, ">", filterValue[0]], 
                        "and", 
                        [this.dataField, "<", filterValue[1]]
                    ];
                    return filterExpression;
                }
                // Invoke the default implementation for other filter operations
                if(!this.defaultCalculateFilterExpression) 
                    return [this.dataField, 'contains', filterValue];  
                return this.defaultCalculateFilterExpression.apply(this, arguments);
            },
            // ...
        }]
    });
});
Angular
TypeScript
HTML
import { DxTreeListModule } from "devextreme-angular";
import { Column } from 'devextreme/ui/data_grid';
// ...
export class AppComponent {
    calculateFilterExpression (this: Column, filterValue, selectedFilterOperation, target) {
        // Override implementation for the "between" filter operation
        if (selectedFilterOperation === "between" && Array.isArray(filterValue)) {
            const filterExpression = [
                [this.dataField, ">", filterValue[0]], 
                "and", 
                [this.dataField, "<", filterValue[1]]
            ];
            return filterExpression;
        }
        // Invoke the default implementation for other filter operations
        if(!this.defaultCalculateFilterExpression) 
            return [this.dataField, 'contains', filterValue];  
        return this.defaultCalculateFilterExpression.apply(this, arguments);
    }
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})
<dx-tree-list ... >
    <dxi-column ...
        [calculateFilterExpression]="calculateFilterExpression">
    </dxi-column>
</dx-tree-list>
Vue
App.vue
<template>
    <DxTreeList>
        <DxColumn ...
            :calculate-filter-expression="calculateFilterExpression"
        />
    </DxTreeList>
</template>

<script>
import 'devextreme/dist/css/dx.light.css';

import DxTreeList, {
    DxColumn
} from 'devextreme-vue/tree-list';

export default {
    components: {
        DxTreeList,
        DxColumn
    },
    data() {
        return {
            calculateFilterExpression (filterValue, selectedFilterOperation, target) {
                // Override implementation for the "between" filter operation
                if (selectedFilterOperation === "between" && Array.isArray(filterValue)) {
                    const filterExpression = [
                        [this.dataField, ">", filterValue[0]], 
                        "and", 
                        [this.dataField, "<", filterValue[1]]
                    ];
                    return filterExpression;
                }
                // Invoke the default implementation for other filter operations
                if(!this.defaultCalculateFilterExpression) 
                    return [this.dataField, 'contains', filterValue];  
                return this.defaultCalculateFilterExpression.apply(this, arguments);
            }
        }
    }
}
</script>
React
App.js
import React from 'react';
import 'devextreme/dist/css/dx.light.css';

import TreeList, {
    Column
} from 'devextreme-react/tree-list';

function calculateFilterExpression (filterValue, selectedFilterOperation, target) {
    // Override implementation for the "between" filter operation
    if (selectedFilterOperation === "between" && Array.isArray(filterValue)) {
        const filterExpression = [
            [this.dataField, ">", filterValue[0]], 
            "and", 
            [this.dataField, "<", filterValue[1]]
        ];
        return filterExpression;
    }
    // Invoke the default implementation for other filter operations
    if(!this.defaultCalculateFilterExpression) 
        return [this.dataField, 'contains', filterValue];  
    return this.defaultCalculateFilterExpression.apply(this, arguments);
}

export default function App() {
    return (
        <TreeList>
            <Column ...
                calculateFilterExpression={calculateFilterExpression}
            />
        </TreeList>
    );
}

View Demo

NOTE

If you specify a custom header filter data source, a header filter item's value field can contain a single value (for example, 0) or a filter expression. If it is a filter expression, the calculateFilterExpression function does not apply.

If you use the search panel, the DataGrid may invoke the calculateFilterExpression function multiple times for lookup columns. The first call is to filter the lookup's data source, and subsequent calls are to filter the DataGrid's data source.

DataGrid uses "anyof" and "noneof" filter values for headerFilter. If you specify calculateFilterExpression for headerFilter, return an array of filterExpressions:

jQuery
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        columns: [{
            calculateFilterExpression(filterValue, selectedFilterOperation, target){
                if (target == "headerFilter") {
                    // ...
                    let filterExpression = ["myDataField", "contains", customValue];
                    return [filterExpression];
                }
            }
            // ...
        }]
    });
});
Angular
TypeScript
HTML
import { DxTreeListModule } from "devextreme-angular";
import { Column } from 'devextreme/ui/data_grid';
// ...
export class AppComponent {
    calculateFilterExpression(this: Column, filterValue, selectedFilterOperation, target){
        if (target == "headerFilter") {
            // ...
            let filterExpression = ["myDataField", "contains", customValue];
            return [filterExpression];
        }
    }
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})
<dx-tree-list ... >
    <dxi-column ...
        [calculateFilterExpression]="calculateFilterExpression">
    </dxi-column>
</dx-tree-list>
Vue
App.vue
<template>
    <DxTreeList>
        <DxColumn ...
            :calculate-filter-expression="calculateFilterExpression"
        />
    </DxTreeList>
</template>

<script>
import 'devextreme/dist/css/dx.light.css';

import DxTreeList, {
    DxColumn
} from 'devextreme-vue/tree-list';

export default {
    components: {
        DxTreeList,
        DxColumn
    },
    data() {
        return {
            calculateFilterExpression(filterValue, selectedFilterOperation, target){
                if (target == "headerFilter") {
                    // ...
                    let filterExpression = ["myDataField", "contains", customValue];
                    return [filterExpression];
                }
            }
        }
    }
}
</script>
React
App.js
import React from 'react';
import 'devextreme/dist/css/dx.light.css';

import TreeList, {
    Column
} from 'devextreme-react/tree-list';

function calculateFilterExpression(filterValue, selectedFilterOperation, target){
    if (target == "headerFilter") {
        // ...
        let filterExpression = ["myDataField", "contains", customValue];
        return [filterExpression];
    }
}

export default function App() {
    return (
        <TreeList>
            <Column ...
                calculateFilterExpression={calculateFilterExpression}
            />
        </TreeList>
    );
}
See Also

calculateSortValue

Calculates custom values used to sort this column.

Type:

String

|

Function

Function parameters:
rowData:

Object

The data of the row to which the cell belongs.

Context: GridBaseColumn

The this keyword refers to the column's configuration.

Return Value: any

The value to be used in sorting.

This property accepts the name of the data source field that provides values used to sort this column.

jQuery
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        columns: [{
            dataField: "Position", // provides column values 
            calculateSortValue: "isOnVacation" // provides values used to sort the Position column
        }]
    });
});
Angular
app.component.html
app.module.ts
<dx-tree-list ... >
    <dxi-column
        dataField="Position" <!-- provides column values -->
        calculateSortValue="isOnVacation"> <!-- provides values used to sort the Position column -->
    </dxi-column>
</dx-tree-list>
import { BrowserModule } from '@angular/platform-browser'; 
import { NgModule } from '@angular/core'; 
import { AppComponent } from './app.component'; 
import { DxDataGridModule } from 'devextreme-angular'; 

@NgModule({ 
    declarations: [ 
        AppComponent 
    ], 
    imports: [ 
        BrowserModule, 
        DxDataGridModule 
    ], 
    providers: [ ], 
    bootstrap: [AppComponent] 
}) 

export class AppModule { }
Vue
App.vue
<template>
    <DxDataGrid ... >
        <DxColumn
            data-field="Position" <!-- provides column values -->
            calculate-sort-value="isOnVacation" <!-- provides values used to sort the Position column -->
        />
    </DxDataGrid>
</template>
<script>
import { DxDataGrid, DxColumn } from 'devextreme-vue/data-grid';

export default {
    components: {
        DxDataGrid,
        DxColumn
    },
    // ...
}
</script>
React
App.js
import React from 'react';
import DataGrid, { Column } from 'devextreme-react/data-grid';

function App() {
    // ...
    return (
        <DataGrid ...>
            <Column
                dataField="Position" // provides column values
                calculateSortValue="isOnVacation" // provides values used to sort the Position column
            />
        </DataGrid>
    );
}

export default App;

... or a function that returns such values. In the code below, calculateSortValue concatenates the State and City column values to sort the Employee column:

jQuery
JavaScript
$(function() {
    var treeList = $("#treeListContainer").dxTreeList({
        columns: [{
            dataField: "Employee",
            sortOrder: "asc",
            calculateSortValue: function (rowData) {
                return rowData.State + rowData.City;
            }
        }]
    }).dxTreeList("instance");
});
Angular
app.component.html
app.component.ts
app.module.ts
<dx-tree-list ... >
    <dxi-column
        dataField="Employee"
        sortOrder="asc"
        [calculateSortValue]="sortByLocation">
    </dxi-column>
</dx-tree-list>
import { DxTreeListModule } from "devextreme-angular";
// ...
export class AppComponent {
    sortByLocation (rowData) {
        return rowData.State + rowData.City;
    }
}
import { BrowserModule } from '@angular/platform-browser'; 
import { NgModule } from '@angular/core'; 
import { AppComponent } from './app.component'; 
import { DxDataGridModule } from 'devextreme-angular'; 

@NgModule({ 
    declarations: [ 
        AppComponent 
    ], 
    imports: [ 
        BrowserModule, 
        DxDataGridModule 
    ], 
    providers: [ ], 
    bootstrap: [AppComponent] 
}) 

export class AppModule { }
Vue
App.vue
<template>
    <DxDataGrid ... >
        <DxColumn
            data-field="Employee"
            :calculate-sort-value="sortByLocation"
        />
    </DxDataGrid>
</template>
<script>
import { DxDataGrid, DxColumn } from 'devextreme-vue/data-grid';

export default {
    components: {
        DxDataGrid,
        DxColumn
    },
    data() {
        return {
            // ...
            sortByLocation(rowData) {
                return rowData.State + rowData.City;
            },
        };
    },
}
</script>
React
App.js
import React from 'react';
import DataGrid, { Column } from 'devextreme-react/data-grid';

function sortByLocation(rowData){
    return rowData.State + rowData.City;
}

function App() {
    // ...
    return (
        <DataGrid ...>
            <Column
                dataField="Employee"
                calculateSortValue={sortByLocation}
            />
        </DataGrid>
    );
}

export default App;
NOTE

calculateSortValue does not affect group rows. To sort them, implement calculateGroupValue in addition to calculateSortValue. You should also define the groupCellTemplate to apply a custom template for group rows.

View on GitHub

See Also

caption

Specifies a caption for the column.

Type:

String

| undefined
Default Value: undefined

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

cellTemplate

Specifies a custom template for data cells.

Type:

template

Template Data:
Name Type Description
column

TreeList Column

The column's properties.
columnIndex

Number

The index of the cell's column.
component

TreeList

The UI component's instance.
data

Object

The data of the row to which the cell belongs.
displayValue any

The cell's display value. Differs from the value field only when the column uses lookup or calculateDisplayValue.
oldValue any

The cell's previous raw value. Defined only if repaintChangesOnly is true.
row

TreeList Row

The cell's row.
rowIndex

Number

The index of the cell's row. Begins with 0 on each page.
Refer to Column and Row Indexes for more information.
rowType

String

The row's type.
text

String

displayValue after applying format and customizeText.
value any

The cell's raw value.
watch

Function

Allows you to track a variable and respond to value changes. Applies when repaintChangesOnly is true.
This function has the following parameters:

  • getter(data): Function
    A function that returns the variable that should be tracked.

  • handler(newValue): Function
    A function called when this variable changes.

NOTE
If you implement two-way data binding in your template, make sure that you have switched off the built-in implementation of this feature by setting the twoWayBindingEnabled property to false.

View Demo

See Also

columns

Configures columns.

Selector: dxi-column
Type:

Array<TreeList Column | String>

Default Value: undefined

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.

jQuery
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        columns: [{
            caption: "Address",
            columns: ["City", "Street", "Apartment"]
        }, {
            // ...
        }]
    });
});
Angular
HTML
TypeScript
<dx-tree-list ... >
    <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-tree-list>
import { DxTreeListModule } from "devextreme-angular";
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})
Vue
App.vue
<template>
    <DxTreeList ... >
        <DxColumn caption="Address">
            <DxColumn data-field="City" />
            <DxColumn data-field="Street" />
            <DxColumn data-field="Apartment" />
        </DxColumn>
    </DxTreeList>
</template>

<script>
import 'devextreme/dist/css/dx.light.css';

import DxTreeList, {
    DxColumn
} from 'devextreme-vue/tree-list';

export default {
    components: {
        DxTreeList,
        DxColumn
    },
    // ...
}
</script>
React
App.js
import React from 'react';
import 'devextreme/dist/css/dx.light.css';

import TreeList, {
    Column
} from 'devextreme-react/tree-list';

export default function App() {
    return (
        <TreeList ... >
            <Column caption="Address">
                <Column dataField="City" />
                <Column dataField="Street" />
                <Column dataField="Apartment" />
            </Column>
        </TreeList>
    );
}

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

NOTE
There is an exception though: nested columns cannot be fixed alone, therefore specifying the fixed and fixedPosition properties for them is useless. However, the whole band column can be fixed as usual.

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

jQuery
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        columns: [{
            caption: "Address",
            fixed: true,
            fixedPosition: "right",
            columns: [
                "City", {
                    dataField: "Street",
                    width: 100,
                    sortOrder: "asc"
                },
                "Apartment"
            ]
        }, {
            // ...
        }]
    });
});
Angular
HTML
TypeScript
<dx-tree-list ... >
    <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-tree-list>
import { DxTreeListModule } from "devextreme-angular";
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})
Vue
App.vue
<template>
    <DxTreeList ... >
        <DxColumn
            caption="Address"
            :fixed="true"
            fixed-position="right">
            <DxColumn data-field="City" />
            <DxColumn data-field="Street" :width="100" sort-order="asc" />
            <DxColumn data-field="Apartment" />
        </DxColumn>
    </DxTreeList>
</template>

<script>
import 'devextreme/dist/css/dx.light.css';

import DxTreeList, {
    DxColumn
} from 'devextreme-vue/tree-list';

export default {
    components: {
        DxTreeList,
        DxColumn
    },
    // ...
}
</script>
React
App.js
import React from 'react';
import 'devextreme/dist/css/dx.light.css';

import TreeList, {
    Column
} from 'devextreme-react/tree-list';

export default function App() {
    return (
        <TreeList ... >
            <Column
                caption="Address"
                fixed={true}
                fixedPosition="right">
                <Column dataField="City" />
                <Column dataField="Street" width={100} sortOrder="asc" />
                <Column dataField="Apartment" />
            </Column>
        </TreeList>
    );
}

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

jQuery
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        columns: [{
            caption: "A",
            columns: [ "A1", "A2", {
                caption: "A3",
                columns: ["A31", "A32", {
                    caption: "A33",
                    columns: ["A331", "A332", "A333"]
                }]
            }]
        }, {
            caption: "B",
            columns: // ...
        }]
    });
});
Angular
HTML
TypeScript
<dx-tree-list ... >
    <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-tree-list>
import { DxTreeListModule } from "devextreme-angular";
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})
Vue
App.vue
<template>
    <DxTreeList ... >
        <DxColumn caption="A">
            <DxColumn data-field="A1" />
            <DxColumn data-field="A2" />
            <DxColumn caption="A3">
                <DxColumn data-field="A31" />
                <DxColumn data-field="A32" />
                <DxColumn caption="A33">
                    <DxColumn data-field="A331" />
                    <DxColumn data-field="A332" />
                    <DxColumn data-field="A333" />
                </DxColumn>
            </DxColumn>
        </DxColumn>
        <DxColumn caption="B">
            ...
        </DxColumn>
    </DxTreeList>
</template>

<script>
import 'devextreme/dist/css/dx.light.css';

import DxTreeList, {
    DxColumn
} from 'devextreme-vue/tree-list';

export default {
    components: {
        DxTreeList,
        DxColumn
    },
    // ...
}
</script>
React
App.js
import React from 'react';
import 'devextreme/dist/css/dx.light.css';

import TreeList, {
    Column
} from 'devextreme-react/tree-list';

export default function App() {
    return (
        <TreeList ... >
            <Column caption="A">
                <Column dataField="A1" />
                <Column dataField="A2" />
                <Column caption="A3">
                    <Column dataField="A31" />
                    <Column dataField="A32" />
                    <Column caption="A33">
                        <Column dataField="A331" />
                        <Column dataField="A332" />
                        <Column dataField="A333" />
                    </Column>
                </Column>
            </Column>
            <Column caption="B">
                ...
            </Column>
        </TreeList>
    );
}

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

See Also

cssClass

Specifies a CSS class to be applied to the column.

Type:

String

| undefined
Default Value: undefined

In the following code, this property is assigned a cell-highlighted CSS class that customizes the position column's cell and header styles:

jQuery
index.js
styles.css
$(function() {
    $("#treeListContainer").dxTreeList({
        dataSource: [{
            ID: 1,
            position: "CTO"
        }, // ...
        ],
        columns: [ "ID", {
            dataField: "position",
            cssClass: "cell-highlighted"
        } ],
    });
})
.dx-data-row .cell-highlighted {
    background-color: #e6e6e6;
}

.dx-header-row .cell-highlighted {
    color: gray;
    font-style: italic;
}
Angular
app.component.html
app.component.ts
app.module.ts
app.component.css
<dx-tree-list ...
    [dataSource]="employees">
    <dxi-column dataField="ID"></dxi-column>
    <dxi-column dataField="position" cssClass="cell-highlighted"></dxi-column>
</dx-tree-list>
import { Component } from '@angular/core';

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css']
})
export class AppComponent {
    employees = [{
        ID: 1,
        position: "CTO"
    }, // ...
    ];
}
import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';

import { DxTreeListModule } from 'devextreme-angular';

@NgModule({
    declarations: [
        AppComponent
    ],
    imports: [
        BrowserModule,
        DxTreeListModule
    ],
    providers: [ ],
    bootstrap: [AppComponent]
})
export class AppModule { }
::ng-deep .dx-data-row .cell-highlighted {
    background-color: #e6e6e6;
}

::ng-deep .dx-header-row .cell-highlighted {
    color: gray;
    font-style: italic;
}
Vue
App.vue
<template>
    <DxTreeList ...
        :data-source="employees">
        <DxColumn data-field="ID" />
        <DxColumn data-field="position" css-class="cell-highlighted" />
    </DxTreeList>
</template>
<script>
import 'devextreme/dist/css/dx.light.css';

import { DxTreeList, DxColumn } from 'devextreme-vue/tree-list';

const employees = [{
    ID: 1,
    position: "CTO"
}, // ...
];

export default {
    components: {
        DxTreeList,
        DxColumn
    },
    data() {
        employees
    }
};
</script>
<style>
.dx-data-row .cell-highlighted {
    background-color: #e6e6e6;
}

.dx-header-row .cell-highlighted {
    color: gray;
    font-style: italic;
}
</style>
React
App.js
styles.css
import React from 'react';

import 'devextreme/dist/css/dx.light.css';

import { TreeList, Column } from 'devextreme-react/tree-list';

const employees = [{
    ID: 1,
    position: "CTO"
}, // ...
];

class App extends React.Component {
    constructor(props) {
        super(props);
    }

    render() {
        return (
            <TreeList ...
                dataSource={employees}>
                <Column dataField="ID" />
                <Column dataField="position" cssClass="cell-highlighted" />
            </TreeList>
        );
    }
}
export default App;
.dx-data-row .cell-highlighted {
    background-color: #e6e6e6;
}

.dx-header-row .cell-highlighted {
    color: gray;
    font-style: italic;
}
ASP.NET MVC Controls
Razor C#
styles.css
@(Html.DevExtreme().TreeList()
    .DataSource(new JS("employees"))
    .Columns(c => {
        c.Add().DataField("ID");
        c.Add().DataField("position").CssClass("cell-highlighted");
    })
)
<script type="text/javascript">
    var employees = [{
        ID: 1,
        position: "CTO"
    }, // ...
    ];
</script>
.dx-data-row .cell-highlighted {
    background-color: #e6e6e6;
}

.dx-header-row .cell-highlighted {
    color: gray;
    font-style: italic;
}

customizeText

Customizes the text displayed in column cells.

Type:

Function

Function parameters:
cellInfo:

Object

Information on the current cell.

Object structure:
Name Type Description
groupInterval

String

|

Number

Indicates how header filter values were combined into groups. Available if target is "headerFilter".
See the headerFilter.groupInterval property's description for possible values.
target

String

The UI element where the customizeText function was called: "row", "filterRow", "headerFilter", "search", "filterPanel", or "filterBuilder".
value any

The cell value.
valueText

String

The formatted value converted to a string.
Context: GridBaseColumn

The this keyword refers to the column's configuration.

Return Value:

String

The text the cell should display.

jQuery
index.js
$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        columns: [{
            dataField: "Temperature",
            customizeText: function(cellInfo) {
                return cellInfo.value + " &deg;C";
            }
        }]
    });
});
Angular
app.component.html
app.component.ts
app.module.ts
<dx-tree-list ... >
   <dxi-column
       dataField="Temperature"
       [customizeText]="customizeText"
   ></dxi-column>
</dx-tree-list>
import { Component } from '@angular/core';

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css']
})
export class AppComponent {
    customizeText(cellInfo) {
        return cellInfo.value + " &deg;C";
    }
}
import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';

import { DxTreeListModule } from 'devextreme-angular';

@NgModule({
    declarations: [
        AppComponent
    ],
    imports: [
        BrowserModule,
        DxTreeListModule
    ],
    providers: [
    ],
    bootstrap: [AppComponent]
})
export class AppModule { }
Vue
App.vue
<template>
    <DxTreeList ... >
        <DxColumn
            data-field="Temperature" 
            :customize-text="customizeText"
        />
    </DxTreeList>
</template>

<script>
import 'devextreme/dist/css/dx.light.css';

import { DxTreeList, DxColumn } from "devextreme-vue/tree-list";

export default {
    components: {
        DxTreeList,
        DxColumn
    },
    methods: {
        customizeText(cellInfo) {
            return cellInfo.value + " &deg;C";
        }
    }
}
</script>
React
App.js
import React from 'react';

import 'devextreme/dist/css/dx.light.css';

import TreeList, { Column } from "devextreme-react/tree-list";

class App extends React.Component {
    customizeText = (cellInfo) => {
        return cellInfo.value + " &deg;C";
    }
    render() {
        return (
            <TreeList ... >
                <Column dataField="Temperature" customizeText={this.customizeText} />
            </TreeList>
        );
    }
}
export default App;
ASP.NET MVC Controls
Razor C#
@(Html.DevExtreme().TreeList()
    //...
    .Columns(columns => {
        columns.Add().DataField("Temperature")
            .CustomizeText("customizeText");
    })
)

<script type="text/javascript">
    function customizeText(cellInfo) {
        return cellInfo.value + " &deg;C";
    }
</script>
NOTE
The component does not use the specified text to sort, filter, and group data or calculate summaries. If you want to implement described functionality, specify the calculateCellValue function.

You can call the customizeText function to highlight the matching text correctly when the data displayed in the column matches the search condition.

See Also

dataField

Binds the column to a field of the dataSource.

Type:

String

| undefined
Default Value: undefined

The columns array can contain column objects and data field names as strings. If you use column objects, specify the dataField property to bind the object to a column from a data source:

jQuery
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        columns: [
            "CustomerID",
            { dataField: "EmployeeID", width: 200 },
            "OrderDate",
            { dataField: "Freight", format: "fixedPoint" },
            "ShipName",
            "ShipCity"
        ]
    });
});
Angular
HTML
TypeScript
<dx-tree-list ... >
    <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-tree-list>
import { DxTreeListModule } from "devextreme-angular";
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})
Vue
App.vue
<template>
    <DxTreeList ... >
        <DxColumn data-field="CustomerID" />
        <DxColumn data-field="EmployeeID" :width="200" />
        <DxColumn data-field="OrderDate" />
        <DxColumn data-field="Freight" format="fixedPoint" />
        <DxColumn data-field="ShipName" />
        <DxColumn data-field="ShipCity" />
    </DxTreeList>
</template>

<script>
import 'devextreme/dist/css/dx.light.css';

import DxTreeList, {
    DxColumn
} from 'devextreme-vue/tree-list';

export default {
    components: {
        DxTreeList,
        DxColumn
    },
    // ...
}
</script>
React
App.js
import React from 'react';
import 'devextreme/dist/css/dx.light.css';

import TreeList, {
    Column
} from 'devextreme-react/tree-list';

export default function App() {
    return (
        <TreeList ... >
            <Column dataField="CustomerID" />
            <Column dataField="EmployeeID" width={200} />
            <Column dataField="OrderDate" />
            <Column dataField="Freight" format="fixedPoint" />
            <Column dataField="ShipName" />
            <Column dataField="ShipCity" />
        </TreeList>
    );
}
NOTE

Review the following notes about data binding:

  • If you create an unbound column (use the calculateCellValue function), specify the columns[].name property instead of dataField.

  • Data field names cannot be equal to this and should not contain the following characters: ., :, [, and ].

  • Column caption is generated from the dataField value. If you want to use a custom caption, specify it in the caption property. Unlike dataField, caption can contain any characters.

See Also

dataType

Casts column values to a specific data type.

Type:

DataType

| undefined
Default Value: undefined

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

jQuery
JavaScript
$(function() {
    $("#treeList").dxTreeList({
        // ...
        dataSource: [{
            ID: "1",
            hireDate: 1491821760000
        }, // ...
        ],
        columns: [{
            dataField: "ID",
            dataType: "number"
        }, {
            dataField: "hireDate",
            dataType: "date"
        }]
    });
})
Angular
HTML
TypeScript
<dx-tree-list ...
    [dataSource]="employees">
    <dxi-column
        dataField="ID"
        dataType="number">
    </dxi-column>
    <dxi-column 
        dataField="hireDate"
        dataType="date">
    </dxi-column>
</dx-tree-list>
import { DxTreeListModule } from 'devextreme-angular';
// ...
export class AppComponent {
    employees = [{
        ID: "1",
        hireDate: 1491821760000
    }, // ...
    ];
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule 
    ],
    // ...
})
ASP.NET MVC Controls
Razor C#
@(Html.DevExtreme().TreeList()
    .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>
Vue
<template>
    <DxTreeList ...
        :data-source="employees">
        <DxColumn
            data-field="ID"
            data-type="number"
        />
        <DxColumn
            data-field="hireDate"
            data-type="date"
        />
    </DxTreeList>
</template>
<script>
import { DxTreeList, DxColumn } from 'devextreme-vue/tree-list';

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

export default {
    components: {
        DxTreeList,
        DxColumn
    },
    data() {
        employees
    }
};
</script>
React
import React from 'react';
import { TreeList, Column } from 'devextreme-react/tree-list';

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

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

editCellTemplate

Specifies a custom template for data cells in an editing state.

Type:

template

Template Data:
Name Type Description
column

TreeList Column

The settings of the column the cell belongs to.
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.
component

TreeList

The UI component's instance.
data

Object

Cell row data.
displayValue any

The displayed cell value. Differs from the value field only when the column uses lookup or calculateDisplayValue.
row

TreeList Row

The cell's row.
rowIndex

Number

The index of the row the cell belongs to. Begins with 0 on each page.
Refer to the Column and Row Indexes topic for more information on row indexes.
rowType

String

The row's type.
setValue(newValue, newText) any

A method called to change cell values; optionally, you can also call it to change the displayed value after the editor's value is changed.
See an example in the Custom Editors demo.

NOTE
In batch editing mode, confirm that the value is changed before calling this method to ensure correct cell highlighting.
text

String

displayValue after applying format and customizeText.
value any

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

Function

Allows you to track a variable and perform actions when it changes. Applies when repaintChangesOnly is true.
This function has the following parameters:

  • getter(data): Function
    A function that returns the variable that should be tracked.

  • handler(newValue): Function
    A function that is called when the variable changes.

Use editCellTemplate to replace the default editor. In the template, specify replacement editor appearance and behavior.

View Demo

Other properties that allow editor customization include:

NOTE

Please review the following notes:

  • If you implement two-way data binding in your template, set twoWayBindingEnabled to false to disable this feature's default implementation.

  • If you specify validationRules, the editCellTemplate must contain a DevExtreme editor to which the TreeList will apply these rules.

  • If a column is fixed or it is hidden with hidingPriority, the template is initialized and rendered twice for each cell.

See Also

editorOptions

Configures the default UI component used for editing and filtering in the filter row.

Type: any

In this object, you can specify the default UI component's properties (except onValueChanged, which you can specify in onEditorPreparing).

The default editor UI component depends on the column configuration. The following table illustrates the dependency:

Column Configuration Default Editor
dataType: "date"
"datetime"		 DateBox
"number" NumberBox
"boolean" CheckBox
"string"
"object"		 TextBox
lookup is defined SelectBox
Angular

Because of this dependency, editorOptions cannot be typed and are not implemented as nested configuration components. Specify editorOptions with an object.

app.component.html
app.module.ts
<dx-tree-list ... >
    <dxi-column ...
        [editorOptions]="{ format: 'currency', showClearButton: true }">
    </dxi-column>
</dx-tree-list>
import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';

import { DxTreeListModule } from 'devextreme-angular';

@NgModule({
    declarations: [
        AppComponent
    ],
    imports: [
        BrowserModule,
        DxTreeListModule
    ],
    providers: [ ],
    bootstrap: [AppComponent]
})
export class AppModule { }
Vue

Because of this dependency, editorOptions cannot be typed and are not implemented as nested configuration components. Specify editorOptions with an object. We recommend that you declare the object outside the configuration component to prevent possible issues caused by unnecessary re-rendering.

App.vue
<template>
    <DxTreeList ... >
        <DxColumn ...
            :editor-options="columnEditorOptions"
        />
    </DxTreeList>
</template>

<script>
import 'devextreme/dist/css/dx.light.css';

import DxTreeList, {
    DxColumn
} from 'devextreme-vue/tree-list';

export default {
    components: {
        DxTreeList,
        DxColumn
    },
    data() {
        return {
            columnEditorOptions: { format: 'currency', showClearButton: true }
        }
    }
}
</script>
React

Because of this dependency, editorOptions cannot be typed and are not implemented as nested configuration components. Specify editorOptions with an object. We recommend that you declare the object outside the configuration component to prevent possible issues caused by unnecessary re-rendering.

App.js
import React from 'react';

import 'devextreme/dist/css/dx.light.css';

import TreeList, {
    Column
} from 'devextreme-react/tree-list';

class App extends React.Component {
    columnEditorOptions = { format: 'currency', showClearButton: true };

    render() {
        return (
            <TreeList ... >
                <Column ...
                    editorOptions={this.columnEditorOptions}
                />
            </TreeList>
        );
    }
}
export default App;

View Demo

Other properties that allow editor customization include:

See Also

encodeHtml

Specifies whether HTML tags are displayed as plain text or applied to the values of the column.

Type:

Boolean

Default Value: true

When true, HTML tags are displayed as plain text; when false, they are applied to the values of the column. If you disable this property, malicious code can be executed. Refer to the following help topic for more information: Potentially Vulnerable API - encodeHtml.

falseText

In a boolean column, replaces all false items with a specified text. Applies only if showEditorAlways property is false.

Type:

String

Default Value: 'false'

See Also

filterOperations

Specifies available filter operations. Applies if allowFiltering is true and the filterRow and/or filterPanel are visible.

Selector: dxi-filter-operation
Type:

Array<FilterOperation | String>

Default Value: undefined

The following table lists available filter operations by data type. Users can apply these filter operations in the filter row and nested filterBuilder component.

NOTE
The default filter operations for each data type are listed in the selectedFilterOperation API section.
dataType filterOperations
"string" [ "contains", "notcontains", "startswith", "endswith", "=", "<>" ]
"numeric" [ "=", "<>", "<", ">", "<=", ">=", "between" ]
"date" [ "=", "<>", "<", ">", "<=", ">=", "between" ]

The nested filter builder also allows users to select from an extended set of operations that include "anyof", "noneof", "isblank", "isnotblank", and names of custom operations (if any).

The filterOperations property can also accept an empty array. In this case, the selectedFilterOperation applies, and users cannot change it.

See Also

filterType

Specifies whether a user changes the current filter by including (selecting) or excluding (clearing the selection of) values. Applies only if headerFilter.visible and allowHeaderFiltering are true.

Type:

FilterType

Default Value: 'include'

This property accepts the following values.

  • include
    Values in the header filter are unselected initially, and a user can select values to apply a filter.
  • exclude
    All values in the header filter are selected initially. A user can deselect values to change the filter.

This property changes when the user clicks the Select All checkbox in the header filter (only if header filter displays plain data):

Select All filterType / filterValues
filterType: "include"
filterValues: null
filterType: "exclude"
filterValues: null
See Also

filterValue

Specifies the value to display in the filter row.

Type: any | undefined
Default Value: undefined
Raised Events: onOptionChanged

When DevExtreme loads the grid, it passes the value of the filterValue property to the selectedFilterOperation method.

Note: Convert date strings into Date objects before you pass them to the filter expression.

NOTE
The filter row and header filter can work simultaneously. If you specify the filterValue property to set up the filter row, it limits the filter values for the header filter and vice versa: if you specify the filterValues property to set up the header filter, it limits the filter row's filter values.

filterValues

Sets the values in the header filter.

Type:

Array<any>

Default Value: undefined
Raised Events: onOptionChanged

Note: Convert date strings into Date objects before you pass them to the filter expression.

If you specify the headerFilter.groupInterval property, each member of the filterValues array indicates the beginning of a value range:

jQuery
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        columns: [{
            dataField: "ID",
            dataType: "number",
            headerFilter: { groupInterval: 100 },
            filterValues: [500, 700], // Filter intervals are 500-600 and 700-800
        },
        // ...
        ]
    })
});
Angular
app.component.html
app.module.ts
<dx-tree-list ... >
    <dxi-column
        dataField="ID"
        dataType="number"
        [filterValues]="[500, 700]"> <!-- Filter intervals are 500-600 and 700-800 -->
        <dxo-header-filter
            [groupInterval]="100">
        </dxo-header-filter>
    </dxi-column>
</dx-tree-list>
import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';

import { DxTreeListModule } from 'devextreme-angular';

@NgModule({
    declarations: [
        AppComponent
    ],
    imports: [
        BrowserModule,
        DxTreeListModule
    ],
    providers: [ ],
    bootstrap: [AppComponent]
})
export class AppModule { }
Vue
App.vue
<template>
    <DxTreeList>
        <DxColumn
            data-field="ID"
            data-type="number"
            :filter-values="[500, 700]"> <!-- Filter intervals are 500-600 and 700-800 -->
            <DxHeaderFilter
                :group-interval="100"
            />
        </DxColumn>
    </DxTreeList>
</template>

<script>
import 'devextreme/dist/css/dx.light.css';

import DxTreeList, {
    DxColumn,
    DxHeaderFilter
} from 'devextreme-vue/tree-list';

export default {
    components: {
        DxTreeList,
        DxColumn,
        DxHeaderFilter
    },
    // ...
}
</script>
React
App.js
import React from 'react';
import 'devextreme/dist/css/dx.light.css';

import TreeList, {
    Column,
    HeaderFilter
} from 'devextreme-react/tree-list';

export default function App() {
    return (
        <TreeList>
            <Column
                dataField="ID"
                dataType="number"
                filterValues={[500, 700]}> {/* Filter intervals are 500-600 and 700-800 */}
                <HeaderFilter
                    groupInterval={100}>
                </HeaderFilter>
            </Column>
        </TreeList>
    );
}
NOTE
The filter row and header filter can work simultaneously. If you specify the filterValue property to set up the filter row, it limits the filter values for the header filter and vice versa: if you specify the filterValues property to set up the header filter, it limits the filter row's filter values.
See Also

fixed

Fixes the column.

Type:

Boolean

Default Value: false

DataGrid Demo TreeList Demo

See Also

fixedPosition

Specifies the column position. Applies only if columns[].fixed is true.

Type:

FixedPosition

| undefined
Default Value: undefined

The following values are available:

  • 'right'
    The column is fixed to the right edge of the grid.

  • 'left'
    The column is fixed to the left edge of the grid.

  • 'sticky'
    The column sticks to left and right edges when it reaches them.

NOTE
If a virtual column rendering mode is enabled, sticky columns have no effect.

DataGrid Demo TreeList Demo

See Also

format

Formats a value before it is displayed in a column cell.

Selector: dxo-format
Type:

Format

Default Value: ''

See the format section for information on accepted values.

In the following code, the "fixedPoint" format type with a precision of 2 decimal places is applied to column values:

jQuery
index.js
$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        columns: [{
            // ...
            format: {
                type: "fixedPoint",
                precision: 2
            }
        }]
    });
});
Angular
app.component.html
app.module.ts
<dx-tree-list ... >
    <dxi-column ... >
        <dxo-format
            type="fixedPoint"
            [precision]="2">
        </dxo-format>
    </dxi-column>
</dx-tree-list>
import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';

import { DxTreeListModule } from 'devextreme-angular';

@NgModule({
    declarations: [
        AppComponent
    ],
    imports: [
        BrowserModule,
        DxTreeListModule
    ],
    providers: [ ],
    bootstrap: [AppComponent]
})
export class AppModule { }
Vue
App.vue
<template>
    <DxTreeList ... >
        <DxColumn ... >
            <DxFormat
                type="fixedPoint"
                :precision="2"
            />
        </DxColumn>
    </DxTreeList>
</template>

<script>
import 'devextreme/dist/css/dx.light.css';

import DxTreeList, {
    DxColumn,
    DxFormat
} from 'devextreme-vue/tree-list';

export default {
    components: {
        DxTreeList,
        DxColumn,
        DxFormat
    },
    data() {
        // ...
    }
}
</script>
React
App.js
import React from 'react';

import 'devextreme/dist/css/dx.light.css';

import TreeList, {
    Column,
    Format
} from 'devextreme-react/tree-list';

class App extends React.Component {
    // ...
    render() {
        return (
            <TreeList>
                <Column ... >
                    <Format
                        type="fixedPoint"
                        precision={2}
                    />
                </Column>
            </TreeList>
        );
    }
}
export default App;

The format property also limits user input in cells that use the DateBox UI component for editing. For cells that use the NumberBox UI component, you can specify the editorOptions.format property, as shown in the following demo:

View Demo

formItem

Configures the form item that the column produces in the editing state. Applies only if editing.mode is "form" or "popup".

Selector: dxo-form-item
Type:

Simple Form Item

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:

jQuery
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        editing: {
            allowUpdating: true,
            mode: "form"
        },
        columns: [{
            dataField: "Full_Name",
            formItem: {
                colSpan: 2,
                label: {
                    location: "top"
                }
            }
        },
        // ...
        ]
    });
});
Angular
HTML
TypeScript
<dx-tree-list ... >
    <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-tree-list>
import { DxTreeListModule } from "devextreme-angular";
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})
Vue
App.vue
<template>
    <DxTreeList ... >
        <DxEditing
            :allow-updating="true"
            mode="form"
        />
        <DxColumn data-field="Full_Name">
            <DxFormItem :col-span="2">
                <DxLabel location="top" />
            </DxFormItem>
        </DxColumn>
    </DxTreeList>
</template>

<script>
import 'devextreme/dist/css/dx.light.css';

import DxTreeList, {
    DxEditing,
    DxColumn,
    DxFormItem,
    DxLabel
} from 'devextreme-vue/tree-list';

export default {
    components: {
        DxTreeList,
        DxEditing,
        DxColumn,
        DxFormItem,
        DxLabel
    },
    // ...
}
</script>
React
App.js
import React from 'react';
import 'devextreme/dist/css/dx.light.css';

import TreeList, {
    Editing,
    Column,
    FormItem,
    Label
} from 'devextreme-react/tree-list';

export default function App() {
    return (
        <TreeList ... >
            <Editing
                allowUpdating={true}
                mode="form"
            />
            <Column dataField="Full_Name">
                <FormItem colSpan={2}>
                    <Label location="top" />
                </FormItem>
            </Column>
        </TreeList>
    );
}
ASP.NET MVC Controls
Razor C#
@(Html.DevExtreme().TreeList()
    // ...
    .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)
            )
        );
    })
)
NOTE

  • The formItem object does not allow you to specify a template. Use the column's editCellTemplate instead.

  • Do not use formItem to override editor's onValueChanged. Implement onEditorPreparing instead.

  • The component does not check validation rules in the formItem object. Use the columns.validationRules property to customize validation instead. For more information, refer to the Data Validation article.

View on GitHub

See Also

headerCellTemplate

Specifies a custom template for column headers.

Type:

template

Template Data:
Name Type Description
column

TreeList Column

The settings of the column to which the header belongs.
columnIndex

Number

The index of the column to which the header belongs.
component

TreeList

The UI component's instance.

See Also

headerFilter

Specifies data settings for the header filter.

Selector: dxo-header-filter
Type:

Object

Default Value: undefined

View Demo

See Also

hidingPriority

Specifies the order in which columns are hidden when the UI component adapts to the screen or container size. Ignored if allowColumnResizing is true and columnResizingMode is "widget".

Type:

Number

| undefined
Default Value: undefined

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

NOTE

  • If you specify this property for at least one column, the column hiding feature is enabled and the default hiding priorities are canceled.

  • Fixed columns ignore the hidingPriority and allowHiding properties.

  • Grouped columns ignore this property.

DataGrid Demo TreeList Demo

See Also

isBand

Specifies whether the column organizes other columns into bands.

Type:

Boolean

| undefined
Default Value: undefined

Unlike standard columns, band columns do not contain data. Instead, a band column displays two or more columns underneath its header. To create a banded layout, do one of the following:

The following code uses the isBand and ownerBand properties to display the "City", "Street", and "Apartment" columns under the "Address" band:

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

            const 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
            }
        }
    });
});
Angular
TypeScript
HTML
import { DxTreeListModule } from "devextreme-angular";
// ...
export class AppComponent {
    customizeColumns (columns) {
        columns.push({ // Pushes the "Address" band column into the "columns" array
            caption: "Address",
            isBand: true
        });

        const 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: [
        // ...
        DxTreeListModule
    ],
    // ...
})
<dx-tree-list ...
    [customizeColumns]="customizeColumns">
</dx-tree-list>
Vue
App.vue
<template>
    <DxTreeList ...
        :customize-columns="customizeColumns">
        <!-- ... -->
    </DxTreeList>
</template>

<script>
import 'devextreme/dist/css/dx.light.css';

import DxTreeList, {
    // ...
} from 'devextreme-vue/tree-list';

export default {
    components: {
        DxTreeList,
        // ...
    },
    // ...
    methods: {
        customizeColumns (columns) {
            columns.push({ // Pushes the "Address" band column into the "columns" array
                caption: "Address",
                isBand: true
            });

            const 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
            }
        }
    }
}
</script>
React
App.js
import React, { useCallback } from 'react';
import 'devextreme/dist/css/dx.light.css';

import TreeList, {
    // ...
} from 'devextreme-react/tree-list';

export default function App() {
    const customizeColumns = useCallback((columns) => {
        columns.push({ // Pushes the "Address" band column into the "columns" array
            caption: "Address",
            isBand: true
        });

        const 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
        }
    }, []);

    return (
        <TreeList ...
            customizeColumns={customizeColumns}>
            {/* ... */}
        </TreeList>
    );
}

Band columns can have the following properties only:

NOTE
Band columns cannot nest command columns.
See Also

lookup

Specifies properties of a lookup column.

Selector: dxo-lookup
Type:

Object

Default Value: undefined

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.

JavaScript
const 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 }
];

const 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 properties. Values from the valueExpr data field will be replaced with values from the displayExpr data field.

jQuery
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        dataSource: drivers,
        // ...
        columns: [{
            dataField: "busID",
            lookup: {
                dataSource: buses,
                valueExpr: "busID",
                displayExpr: "plates"
            }
        }]
    });
});
Angular
HTML
TypeScript
<dx-tree-list [dataSource]="drivers">
    <dxi-column dataField="busID">
        <dxo-lookup
            [dataSource]="buses"
            valueExpr="busID"
            displayExpr="plates">
        </dxo-lookup>
    </dxi-column>
</dx-tree-list>
import { DxTreeListModule } 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: [
        // ...
        DxTreeListModule
    ],
    // ...
})
Vue
App.vue
<template>
    <DxTreeList ...
        :data-source="drivers">
        <DxColumn data-field="busID">
            <DxLookup
                :data-source="buses"
                value-expr="busID"
                display-expr="plates"
            />
        </DxColumn>
    </DxTreeList>
</template>

<script>
import 'devextreme/dist/css/dx.light.css';

import DxTreeList, {
    DxColumn,
    DxLookup
} from 'devextreme-vue/tree-list';

const 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 }
];

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

export default {
    components: {
        DxTreeList,
        DxColumn,
        DxLookup
    },
    data() {
        return {
            drivers,
            buses
        }
    }
}
</script>
React
App.js
import React from 'react';
import 'devextreme/dist/css/dx.light.css';

import TreeList, {
    Column,
    Lookup
} from 'devextreme-react/tree-list';

const 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 }
];

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

export default function App() {
    return (
        <TreeList ...
            dataSource={drivers}>
            <Column dataField="busID">
                <Lookup
                    dataSource={buses}
                    valueExpr="busID"
                    displayExpr="plates"
                />
            </Column>
        </TreeList>
    );
}

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 View on GitHub

See Also

minWidth

Specifies the minimum width of the column.

Type:

Number

| undefined
Default Value: undefined

See Also

name

Specifies the column's unique identifier. If not set in code, this value is inherited from the dataField.

Type:

String

| undefined
Default Value: undefined

This property's value is used to refer to the column in code, for example, when changing a column property.

ownerBand

Specifies the band column that owns the current column. Accepts the index of the band column in the columns array.

Type:

Number

| undefined
Default Value: undefined

Main article: isBand

renderAsync

Specifies whether to render the column after other columns and elements. Use if column cells have a complex template. Requires the width property specified.

Type:

Boolean

Default Value: false

See Also

selectedFilterOperation

Specifies a filter operation that applies when users use the filter row to filter the column.

Type:

SelectedFilterOperation

| undefined
Default Value: undefined
Raised Events: onOptionChanged

The following table lists default selected filter operations by data type:

dataTypeDefault filter operation
"string""contains"
"number""="
"date""="
See Also

setCellValue

Specifies a function to be invoked after the user has edited a cell value, but before it is saved in the data source.

Type:

Function

Function parameters:
newData:

Object

The data object where new data should be set.

value: any

The input value.

currentRowData:

Object

A read-only parameter providing access to the current row data.

Context: GridBaseColumn

The this keyword refers to the column's configuration.

Return Value: void |

Promise<void> (jQuery or native)

Return a promise for an asynchronous operation or return nothing.

This function allows you to process user input before it is saved to the data source. It accepts the newData, value, and currentRowData parameters. value is the user input that you should assign to one of the newData fields. Fill the empty newData object with fields whose values should be saved in the current row's data object. You can use the read-only currentRowData parameter to access the current row's data.

jQuery
index.js
$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        columns: [
            "Price",
            {
                dataField: "Count",
                dataType: "number",
                setCellValue: function(newData, value, currentRowData) {
                    newData.Count = value;
                    newData.TotalPrice = currentRowData.Price * value;
                }
            },
            "TotalPrice",
            // ...
        ]
    });
});
Angular
app.component.html
app.component.ts
app.module.ts
<dx-tree-list ... >
    <dxi-column dataField="Price"></dxi-column>
    <dxi-column
        dataField="Count"
        dataType="number"
        [setCellValue]="setCellValue">
    </dxi-column>
    <dxi-column dataField="TotalPrice"></dxi-column>
</dx-tree-list>
import { Component } from '@angular/core';

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css']
})
export class AppComponent {
    setCellValue (newData, value, currentRowData) {
        newData.Count = value;
        newData.TotalPrice = currentRowData.Price * value;
    }
}
import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';

import { DxTreeListModule } from 'devextreme-angular';

@NgModule({
    declarations: [
        AppComponent
    ],
    imports: [
        BrowserModule,
        DxTreeListModule
    ],
    providers: [ ],
    bootstrap: [AppComponent]
})
export class AppModule { }
Vue
App.vue
<template>
    <DxTreeList ... >
        <DxColumn data-field="Price" />
        <DxColumn data-field="Count" data-type="number" :set-cell-value="setCellValue" />
        <DxColumn data-field="TotalPrice" />
    </DxTreeList>
</template>
<script>
import 'devextreme/dist/css/dx.light.css';

import { DxTreeList, DxColumn } from 'devextreme-vue/tree-list';

export default {
    components: {
        DxTreeList,
        DxColumn
    },
    // ...
    methods: {
        setCellValue(newData, value, currentRowData) {
            newData.Count = value;
            newData.TotalPrice = currentRowData.Price * value;
        }
    }
};
</script>
React
App.js
import React from 'react';

import 'devextreme/dist/css/dx.light.css';

import { TreeList, Column } from 'devextreme-react/tree-list';

class App extends React.Component {
    setCellValue(newData, value, currentRowData) {
        newData.Count = value;
        newData.TotalPrice = currentRowData.Price * value;
    }

    render() {
        return (
            <TreeList ... >
                <Column dataField="Price" />
                <Column dataField="Count" dataType="numeric" setCellValue={this.setCellValue}/>
                <Column dataField="TotalPrice" />
            </TreeList>
        );
    }
}
export default App;
ASP.NET MVC Controls
Razor C#
@(Html.DevExtreme().TreeList()
    // ...
    .Columns(c => {
        c.Add().DataField("Price");
        c.Add().DataField("Count")
            .DataType(GridColumnDataType.Number)
            .SetCellValue(@<text>
                function(newData, value, currentRowData) {
                    newData.Count = value;
                    newData.TotalPrice = currentRowData.Price * value;
                }
            </text>);
        c.Add().DataField("TotalPrice");
    })
)

The setCellValue property forces the component to repaint all items in the edit form. Set repaintChangesOnly to true so the component re-renders only the fields with the changed values.

To perform asynchronous operations in the setCellValue function, return a promise from it. The following code uses this technique to get the Tax value from the server when the State value is changed:

jQuery
index.js
$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        columns: [{
            dataField: "State",
            setCellValue: function(newData, value, currentRowData) {
                return getTaxRates(value)
                    .done(function(data) {
                        newData.State = value;
                        newData.Tax = data.Tax;
                    });
            }
        },
        "Tax",
        // ...
        ]
    });
    function getTaxRates(state) {
        var promise = $.ajax({
            // The URL returns { State: 1, Tax: 10 }
            url: "https://www.mywebsite.com/api/getTaxRates",
            dataType: "json",
            data: { State: state }
        });
        return promise;
    }
});
Angular
app.component.html
app.component.ts
app.module.ts
<dx-tree-list ... >
    <dxi-column
        dataField="State"
        [setCellValue]="setCellValue">
    </dxi-column>
    <dxi-column dataField="Tax"></dxi-column>
    <!-- ... -->
</dx-tree-list>
import { Component } from '@angular/core';
import { HttpClient, HttpParams } from '@angular/common/http';
import { lastValueFrom } from 'rxjs';

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css']
})
export class AppComponent {
    constructor(private httpClient: HttpClient) {
        this.setCellValue = this.setCellValue.bind(this);
    }

    setCellValue(newData, value, currentRowData) {
        return this.getTaxRates(value).then((data: any) => {
            newData.State = value;
            newData.Tax = data.Tax;
        });
    }
    getTaxRates(state) {
        const params = new HttpParams().set('State', state);
        return new Promise(async (resolve, reject) => {
            try {
                const data = await lastValueFrom(this.httpClient.get("https://www.mywebsite.com/api/getTaxRates", { params }));
                // "data" is { State: 1, Tax: 10 }
                resolve(data);
            } catch (error) {
                console.error("Data Loading Error", error);
                reject("Data Loading Error");
            }
        });
    }
}
import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';
import { HttpClientModule } from '@angular/common/http';

import { DxTreeListModule } from 'devextreme-angular';

@NgModule({
    declarations: [
        AppComponent
    ],
    imports: [
        BrowserModule,
        HttpClientModule,
        DxTreeListModule
    ],
    providers: [ ],
    bootstrap: [AppComponent]
})
export class AppModule { }
Vue
App.vue
<template>
    <DxTreeList ... >
        <DxColumn data-field="State" :set-cell-value="setCellValue" />
        <DxColumn data-field="Tax" />
        <!-- ... -->
    </DxTreeList>
</template>
<script>
import 'devextreme/dist/css/dx.light.css';

import { DxTreeList, DxColumn } from 'devextreme-vue/tree-list';
import 'whatwg-fetch';

export default {
    components: {
        DxTreeList,
        DxColumn
    },
    // ...
    methods: {
        setCellValue(newData, value, currentRowData) {
            return this.getTaxRates(value).then(data => {
                newData.State = value;
                newData.Tax = data.Tax;
            });
        },
        getTaxRates(state) {
            let params = '?' + 'State=' + state;
            return fetch("https://www.mywebsite.com/api/getTaxRates${params}")
                .toPromise()
                .then(data => {
                    // "data" is { State: 1, Tax: 10 }
                    return data;
                })
                .catch(error => { throw "Data Loading Error" });
        }
    }
};
</script>
React
App.js
import React from 'react';

import 'devextreme/dist/css/dx.light.css';

import { TreeList, Column } from 'devextreme-react/tree-list';
import 'whatwg-fetch';

class App extends React.Component {
    constructor(props) {
        super(props);
        this.setCellValue = this.setCellValue.bind(this);
    }

    setCellValue(newData, value, currentRowData) {
        return this.getTaxRates(value).then(data => {
            newData.State = value;
            newData.Tax = data.Tax;
        });
    }
    getTaxRates(state) {
        let params = '?' + 'State=' + state;
        return fetch("https://www.mywebsite.com/api/getTaxRates${params}")
            .toPromise()
            .then(data => {
                // "data" is { State: 1, Tax: 10 }
                return data;
            })
            .catch(error => { throw "Data Loading Error" });
    }

    render() {
        return (
            <TreeList ... >
                <Column dataField="State" setCellValue={this.setCellValue}/>
                <Column dataField="Tax" />
                {/* ... */}
            </TreeList>
        );
    }
}
export default App;
ASP.NET MVC Controls
Razor C#
@(Html.DevExtreme().TreeList()
    // ...
    .Columns(c => {
        c.Add().DataField("State")
            .SetCellValue("setCellValue");
        c.Add().DataField("Tax");
        // ...
    })
)
<script type="text/javascript">
    function setCellValue(newData, value, currentRowData) {
        return getTaxRates(value).done(function(data) {
            newData.State = value;
            newData.Tax = data.Tax;
        });
    }
    function getTaxRates(state) {
        var promise = $.ajax({
            // The URL returns { State: 1, Tax: 10 }
            url: "https://www.mywebsite.com/api/getTaxRates",
            dataType: "json",
            data: { State: state }
        });
        return promise;
    }
</script>

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

View on GitHub

showEditorAlways

Specifies whether the column displays its values in editors.

Type:

Boolean

Default Value: false

Set the showEditorAlways property to true to display a column cell value in an editor when a user does not edit data. For example, you can use this functionality to display Boolean data as check boxes instead of the "true/false" strings.

Behavior of the editor in a cell depends on the component's edit mode:

  • The editing.mode property is set to "cell" or "batch". Users can edit values directly in their cells without switching the component to edit mode.

  • The editing.mode property is set to "row", "form" or "popup". Relevant only for Boolean values. The component displays Boolean values in read-only check boxes. Users should click the Edit button to change cell values.

NOTE

This property has the following specifics:

  • The default value of this property depends on the column's dataType. For Boolean columns, the default value is true; for columns of other types - false.

  • The editCellTemplate has higher priority over the cellTemplate if the showEditorAlways property value is true. Relevant for all data types except Boolean.

  • The cellInfo.setValue function does not work when the showEditorAlways property value is true but you do not switch the component to edit mode.

The following example illustrates how this property works for the Boolean and Date data types:

DevExtreme DataGrid TreeList - showEditorAlways

jQuery
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        columns: [
            { 
                dataField: "BirthDate", 
                dataType: 'date'
            },
            { 
                dataField: "OrderDate", 
                dataType: 'date',
                showEditorAlways: true
            },
            //...
            { 
                dataField: "CheckedState", 
                dataType: 'boolean',
                showEditorAlways: false
            },
            { 
                dataField: "AvailabilityState", 
                dataType: 'boolean'
            },
            // ...
        ]
    });
});
Angular
HTML
TypeScript
<dx-tree-list ... >
    <dxi-column dataField="BirthDate" dataType="date"></dxi-column>
    <dxi-column dataField="OrderDate" dataType="date" showEditorAlways="true"></dxi-column>
    <dxi-column dataField="CheckedState" dataType="boolean" showEditorAlways="false"></dxi-column>
    <dxi-column dataField="AvailabilityState" dataType="boolean" ></dxi-column>
</dx-tree-list>
import { DxTreeListModule } from "devextreme-angular";
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})
Vue
App.vue
<template>
    <DxTreeList ... >
        <DxColumn
            data-field="BirthDate"
            data-type="date"
        />
        <DxColumn
            data-field="OrderDate"
            data-type="date"
            :show-editor-always="true"
        />
        <DxColumn
            data-field="CheckedState"
            data-type="boolean"
            :show-editor-always="false"
        />
        <DxColumn
            data-field="AvailabilityState"
            data-type="boolean"
        />
    </DxTreeList>
</template>

<script>
import 'devextreme/dist/css/dx.light.css';

import DxTreeList, {
    DxColumn
} from 'devextreme-vue/tree-list';

export default {
    components: {
        DxTreeList,
        DxColumn
    },
    // ...
}
</script>
React
App.js
import React from 'react';
import 'devextreme/dist/css/dx.light.css';

import TreeList, {
    Column
} from 'devextreme-react/tree-list';

export default function App() {
    return (
        <TreeList ... >
            <Column
                dataField="BirthDate"
                dataType="date"
            />
            <Column
                dataField="OrderDate"
                dataType="date"
                showEditorAlways={true}
            />
            <Column
                dataField="CheckedState"
                dataType="boolean"
                showEditorAlways={false}
            />
            <Column
                dataField="AvailabilityState"
                dataType="boolean"
            />
        </TreeList>
    );
}
See Also

showInColumnChooser

Specifies whether the column chooser can contain the column header.

Type:

Boolean

Default Value: true

See Also

sortIndex

Specifies the index according to which columns participate in sorting.

Type:

Number

| undefined
Default Value: undefined
Raised Events: onOptionChanged

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

JavaScript
const 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 property should also be specified.

jQuery
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        columns: [
            { dataField: "firstName", sortIndex: 1, sortOrder: "asc" },
            { dataField: "lastName", sortIndex: 0, sortOrder: "asc" },
            // ...
        ]
    });
});
Angular
HTML
TypeScript
<dx-tree-list ... >
    <dxi-column dataField="firstName" [sortIndex]="1" sortOrder="asc"></dxi-column>
    <dxi-column dataField="lastName" [sortIndex]="0" sortOrder="asc"></dxi-column>
</dx-tree-list>
import { DxTreeListModule } from "devextreme-angular";
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})
Vue
App.vue
<template>
    <DxTreeList ... >
        <DxColumn
            data-field="firstName"
            :sort-index="1"
            sort-order="asc"
        />
        <DxColumn
            data-field="lastName"
            :sort-index="0"
            sort-order="asc"
        />
    </DxTreeList>
</template>

<script>
import 'devextreme/dist/css/dx.light.css';

import DxTreeList, {
    DxColumn
} from 'devextreme-vue/tree-list';

export default {
    components: {
        DxTreeList,
        DxColumn
    },
    // ...
}
</script>
React
App.js
import React from 'react';
import 'devextreme/dist/css/dx.light.css';

import TreeList, {
    Column
} from 'devextreme-react/tree-list';

export default function App() {
    return (
        <TreeList ... >
            <Column
                dataField="firstName"
                sortIndex={1}
                sortOrder="asc"
            />
            <Column
                dataField="lastName"
                sortIndex={0}
                sortOrder="asc"
            />
        </TreeList>
    );
}

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

sortingMethod

Specifies a custom comparison function for sorting. Applies only when sorting is performed on the client.

Type:

Function

| undefined
Function parameters:
value1: any

A value to be compared.

value2: any

A value to be compared.

Context: GridBaseColumn

The this keyword refers to the column's configuration.

Return Value:

Number

Specifies whether value1 goes before value2.

Default Value: undefined

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:

jQuery
JavaScript
$(function () {
    $("#treeListContainer").dxTreeList({
        // ...
        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);
            }
        }]
    });
});
Angular
TypeScript
HTML
import { DxTreeListModule } 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: [
        // ...
        DxTreeListModule
    ],
    // ...
})
<dx-tree-list ... >
    <dxi-column
        dataField="fieldName"
        [sortingMethod]="sortStringsConsideringCulture">
    </dxi-column>
</dx-tree-list>
Vue
App.vue
<template>
    <DxTreeList ... >
        <DxColumn
            data-field="fieldName"
            :sorting-method="sortStringsConsideringCulture"
        />
    </DxTreeList>
</template>

<script>
import 'devextreme/dist/css/dx.light.css';

import DxTreeList, {
    DxColumn
} from 'devextreme-vue/tree-list';

export default {
    components: {
        DxTreeList,
        DxColumn
    },
    // ...
    methods: {
        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);
        }
    }
}
</script>
React
App.js
import React from 'react';
import 'devextreme/dist/css/dx.light.css';

import TreeList, {
    Column
} from 'devextreme-react/tree-list';

function 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);
}

export default function App() {
    return (
        <TreeList ... >
            <Column
                dataField="fieldName"
                sortingMethod={sortStringsConsideringCulture}
            />
        </TreeList>
    );
}
NOTE
The sortingMethod's value1 and value2 are the values returned from the calculateSortValue function if the latter is specified.

sortOrder

Specifies the sort order of column values.

Type:

SortOrder

| undefined
Default Value: undefined
Accepted Values: undefined
Raised Events: onOptionChanged

By default, rows are sorted according to the data source. To sort rows in an ascending or descending order, set the sortOrder property to "asc" or "desc". If you need to sort by multiple columns, specify the sortIndex. Otherwise, each sorted column will get a sort index according to its position in the columns array.

View Demo

See Also

trueText

In a boolean column, replaces all true items with a specified text. Applies only if showEditorAlways property is false.

Type:

String

Default Value: 'true'

See Also

type

Specifies the command column that this object customizes.

Type:

TreeListCommandColumnType

See Also

validationRules

Specifies validation rules to be checked when cell values are updated.

Selector: dxi-validation-rule
Type:

Array<RequiredRule | NumericRule | RangeRule | StringLengthRule | CustomRule | CompareRule | PatternRule | EmailRule | AsyncRule>

View Demo

See Also

visible

Specifies whether the column is visible, that is, occupies space in the table.

Type:

Boolean

Default Value: true
Raised Events: onOptionChanged

DataGrid Demo TreeList Demo

visibleIndex

Specifies the position of the column regarding other columns in the resulting UI component.

Type:

Number

| undefined
Default Value: undefined
Raised Events: onOptionChanged

Visible indexes are normalized after the UI component's creation: the leftmost column is assigned an index of 0; the rightmost column's index becomes equal to the number of visible columns minus 1; other columns get the indexes in between.

IMPORTANT
This index is used in column reordering only. Do not confuse it with the visible column index, which is used to manipulate cells by calling methods, such as getCellElement(rowIndex, visibleColumnIndex), editCell(rowIndex, visibleColumnIndex), etc.
See Also

width

Specifies the column's width in pixels or as a percentage. Ignored if it is less than minWidth.

Type:

Number

|

String

| undefined
Default Value: undefined

The property 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") except relative units such as em, ch, vh, etc.

    NOTE
    Fixed columns ignore widths specified as a percentage.

DataGrid Demo TreeList Demo

See Also