React TreeList Props

An object defining configuration options for the TreeList widget.

accessKey

Specifies the shortcut key that sets focus on the widget.

Type:

String

Default Value: null

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

activeStateEnabled

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

Type:

Boolean

Default Value: false

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

allowColumnReordering

Specifies whether a user can reorder columns.

Type:

Boolean

Default Value: false

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

See Also

allowColumnResizing

Specifies whether a user can resize columns.

Type:

Boolean

Default Value: false

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

See Also

autoExpandAll

Specifies whether all rows are expanded initially.

Type:

Boolean

Default Value: false

cacheEnabled

Specifies whether data should be cached.

Type:

Boolean

Default Value: true

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

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

See Also

cellHintEnabled

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

Type:

Boolean

Default Value: true

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

columnAutoWidth

Specifies whether columns should adjust their widths to the content.

Type:

Boolean

Default Value: false

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

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

See Also

columnChooser

Configures the column chooser.

Type:

Object

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

DevExtreme HTML5 JavaScript jQuery Angular Knockout TreeList Column Chooser

See Also

columnFixing

Configures column fixing.

Type:

Object

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

DevExtreme HTML5 JavaScript jQuery Angular Knockout TreeList Column Fixing

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

DataGrid Demo TreeList Demo

See Also

columnHidingEnabled

Specifies whether the widget should hide columns to adapt to the screen or container size. Ignored if allowColumnResizing is true and columnResizingMode is "widget".

Type:

Boolean

Default Value: false

This option set to true makes the widget hide certain columns automatically if all the columns do not fit the widget's width. Columns with low hidingPriority are hidden first. These are the rightmost (leftmost if rtlEnabled is true) columns by default. Information from hidden columns is available in an adaptive detail row.

See Also

columnMinWidth

Specifies the minimum width of columns.

Type:

Number

Default Value: undefined

columnResizingMode

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

Type:

String

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

The columnResizingMode option accepts one of the following values:

  • nextColumn
    When a user resizes a column, the width of the next column changes.
  • widget
    When a user resizes a column, the width of the widget changes.
    This mode is ignored if you specify the width of any column in percent.

columns[]

Configures columns.

Default Value: undefined
Raised Events: onOptionChanged

This option 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
    ],
    // ...
})
See Also

columnWidth

Specifies the width for all data columns. Has a lower priority than the column.width option.

Type:

Number

Default Value: undefined

See Also

customizeColumns

Customizes columns after they are created.

Type:

Function

Function parameters:

All column configurations.

Use this function to make minor adjustments to automatically generated columns. You can access and modify column configurations using the function's parameter.

jQuery
JavaScript
$(function(){
    $("#treeList").dxTreeList({
        // ...
        customizeColumns: function (columns) {
            columns[0].width = 100;
            columns[1].width = 210;
        }
    })
});
Angular
TypeScript
HTML
import { DxTreeListModule } from "devextreme-angular";
// ...
export class AppComponent {
    customizeColumns (columns) {
        columns[0].width = 100;
        columns[1].width = 210;
    }
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})
<dx-tree-list ...
    [customizeColumns]="customizeColumns">
</dx-tree-list>

For a more profound column customization, declare the columns array.

dataSource

Specifies the origin of data for the widget.

Default Value: null

This option accepts one of the following:

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

  • URL
    The URL of a JSON file or service that returns JSON data.

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

    NOTE
    If you use data mapping, features like export and selection may work incorrectly. We recommend using calculated columns instead of mapping.
NOTE
Data field names should not contain the following characters: ., ,, :, [, and ]. Their presence may cause issues in the widget's operation.

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

See Also

dataStructure

Notifies the widget of your data structure.

Type:

String

Default Value: 'plain'
Accepted Values: 'plain' | 'tree'

By default, the widget expects that data has a plain structure where each data item contains a "parentId" field and a unique "id" field. For items of the highest hierarchical level, "parentId" should be 0, null or undefined indicating that these items belong to the root node. The root node holds the entire hierarchy and is not visualized.

JavaScript
var treeListData = [
    { id: 1, parentId: 0 },
    { id: 11, parentId: 1 },
    { id: 12, parentId: 1 },
    { id: 13, parentId: 1 },
    { id: 131, parentId: 13 },
    { id: 132, parentId: 13 },
    { id: 133, parentId: 13 },
    { id: 2, parentId: 0 }
];

View Demo

If your data has a hierarchical structure where each data item contains nested items, set this option to "tree". Parent and item IDs will be generated automatically.

JavaScript
var treeListData = [{
    text: "item1",
    items: [{ 
        text: "item11" 
    }, { 
        text: "item12",
        items: [
            { text: "item121" }, 
            { text: "item122" }
        ]
    }]
}, { 
    text: "item2" 
}];

View Demo

See Also

dateSerializationFormat

Specifies date-time values' serialization format. Use it only if you do not specify the dataSource at design time.

Type:

String

Without a data source, the widget cannot detect the date-time values' format. In this case, specify the dateSerializationFormat option that supports the following formats:

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

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

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

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

This option applies only if the forceIsoDateParsing field is set to true in the global configuration object.

disabled

Specifies whether the widget responds to user interaction.

Type:

Boolean

Default Value: false

editing

Configures editing.

Type:

Object

The widget allows a user to edit data in several modes, which are detailed in the mode option. To define what editing operations a user can perform, specify the allowAdding, allowUpdating and allowDeleting options. Before enabling an operation, make sure that your data source supports it.

NOTE
Editing works with plain data only.

Watch Video

See Also

elementAttr

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

Type:

Object

Default Value: {}

jQuery
$(function(){
    $("#treeListContainer").dxTreeList({
        // ...
        elementAttr: {
            id: "elementId",
            class: "class-name"
        }
    });
});
Angular
HTML
TypeScript
<dx-tree-list ...
    [elementAttr]="{ id: 'elementId', class: 'class-name' }">
</dx-tree-list>
import { DxTreeListModule } from "devextreme-angular";
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})
ASP.NET MVC Control
Razor C#
Razor VB
@(Html.DevExtreme().TreeList()
    .ElementAttr("class", "class-name")
    // ===== or =====
    .ElementAttr(new {
        @id = "elementId",
        @class = "class-name"
    })
    // ===== or =====
    .ElementAttr(new Dictionary<string, object>() {
        { "id", "elementId" },
        { "class", "class-name" }
    })

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

errorRowEnabled

Indicates whether to show the error row.

Type:

Boolean

Default Value: true

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

See Also

expandedRowKeys

Specifies keys of the initially expanded rows.

Type:

Array<any>

Default Value: []
Raised Events: onOptionChanged

Setting this option expands only the specified rows, but not their parents. If a to-be-expanded row lies deep in the hierarchy, make sure to include keys of all rows that nest it.

See Also

expandNodesOnFiltering

Specifies whether nodes appear expanded or collapsed after filtering is applied.

Type:

Boolean

Default Value: true

filterBuilder

Configures the integrated filter builder.

Default Value: {}

See the FilterBuilder configuration for options that you can specify in this object.

NOTE
The fields of a configuration object passed to this option do not support two-way binding in Angular, AngularJS, and Knockout and event bindings in Angular.
See Also

filterBuilderPopup

Configures the popup in which the integrated filter builder is shown.

Default Value: {}

See the Popup configuration for options that you can specify in this object.

NOTE
The fields of a configuration object passed to this option do not support two-way binding in Angular, AngularJS, and Knockout and event bindings in Angular.
See Also

filterPanel

Configures the filter panel.

Type:

Object

Default Value: {}

The filter panel displays the applied filter expression.

DevExtreme HTML5 JavaScript jQuery Angular Knockout TreeList Filter Panel

Clicking on the filter expression opens the filter builder.

DevExtreme HTML5 JavaScript jQuery Angular Knockout TreeList Filter Panel

If you change the filter expression in the filter panel or filter builder, the changes are reflected in the filter row and header filter, and vice versa. You can disable this synchronization by setting the filterSyncEnabled option to false. In this case, the filter panel remains synchronized with the filter builder.

See Also

filterRow

Configures the filter row.

Type:

Object

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

DevExtreme HTML5 JavaScript jQuery Angular Knockout Widget TreeList FilterRow

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

DevExtreme HTML5 JavaScript jQuery Angular Knockout Widget TreeList FilterRow

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

View Demo

See Also

filterSyncEnabled

Specifies whether to synchronize the filter row, header filter, and filter builder. The synchronized filter expression is stored in the filterValue option.

Type:

Boolean

Synchronization is enabled if the filter panel is visible. When it is enabled, check that each column that allows filtering has the dataField or name option specified.

filterValue

Specifies a filter expression.

Default Value: null
Raised Events: onOptionChanged

If filterSyncEnabled is true, the filter expression includes a combination of the filter row, header filter, and filter builder filters. Otherwise, it contains only the filter builder filter.

The filter expression can contain the following operations: "=", "<>", "<", ">", "<=", ">=", "between", "contains", "notcontains", "startswith", "endswith", "anyof", "noneof", and the filter builder's custom operations. Use "anyof" and "noneof" to select and clear the selection of items in the header filter's popup menu. In the following code, "anyof" is used to select items with IDs 500 and 700:

jQuery
JavaScript
$(function() {
    $("treeListContainer").dxTreeList({
        // ...
        filterSyncEnabled: true,
        headerFilter: { visible: true },
        filterValue: ["ID", "anyof", [500, 700]], 
    })
});
Angular
HTML
TypeScript
<dx-tree-list ...
    [filterSyncEnabled]="true"
    [(filterValue)]="['ID', 'anyof', [500, 700]]"> 
    <dxo-header-filter 
        [visible]="true">
    </dxo-header-filter>
</dx-tree-list>
import { DxTreeListModule } from "devextreme-angular";
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})

If a column's groupInterval option is set, the "anyof" and "noneof" operations for this column accept the beginning of intervals instead of exact values:

jQuery
JavaScript
$(function() {
    $("treeListContainer").dxTreeList({
        // ...
        filterValue: ["ID", "anyof", [500, 700]], // Filter intervals are 500-600 and 700-800
        columns: [{
            dataField: "ID",
            dataType: "number",
            headerFilter: { groupInterval: 100 }
        },
        // ...
        ]
    })
});
Angular
HTML
TypeScript
<dx-tree-list ...
    <!-- Filter intervals are 500-600 and 700-800 -->
    [(filterValue)]="['ID', 'anyof', [500, 700]]"> 
        <dxi-column
            dataField="ID"
            dataType="number">
                <dxo-header-filter 
                    [groupInterval]="100">
                </dxo-header-filter>
        </dxi-column>
</dx-tree-list>
import { DxTreeListModule } from "devextreme-angular";
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})
NOTE
The DataSource does not support the "anyof", "noneof", and custom operations. Use the getCombinedFilter(returnDataField) method to get the DataSource-compatible filter expression.
See Also

focusStateEnabled

Specifies whether the widget can be focused using keyboard navigation.

Type:

Boolean

Default Value: false

hasItemsExpr

Specifies which data field defines whether the node has children.

Type:

String

|

Function

If you load data from the server, you need to set this option so that the widget does not render the expand button for nodes without children.

headerFilter

Configures the header filter feature.

Type:

Object

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

DevExtreme HTML5 JavaScript jQuery Angular Knockout Widget TreeList HeaderFilter

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

View Demo

See Also

height

Specifies the widget's height.

Type:

Number

|

String

|

Function

Return Value:

Number

|

String

The widget's height.

Default Value: undefined

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

  • Number
    The height in pixels.

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

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

    JavaScript
    height: function() {
        return window.innerHeight / 1.5;
    }

hint

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

Type:

String

Default Value: undefined

hoverStateEnabled

Specifies whether to highlight rows when a user moves the mouse pointer over them.

Type:

Boolean

Default Value: false

itemsExpr

Specifies which data field contains nested items. Set this option when your data has a hierarchical structure.

Type:

String

|

Function

Default Value: 'items'

keyExpr

Specifies which data field provides keys for nodes.

Type:

String

|

Function

Default Value: 'id'

See Also

loadPanel

Configures the load panel.

Type:

Object

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

DevExtreme HTML5 JavaScript jQuery Angular Knockout Widget DataGrid TreeList LoadPanel

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

See Also

noDataText

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

Type:

String

Default Value: 'No data'

onAdaptiveDetailRowPreparing

A function that is executed before an adaptive detail row is rendered.

Type:

Function

Function parameters:
e:

Object

Information about the event that caused the function's execution.

Object structure:
Name Type Description
component

TreeList

The widget's instance.

element

HTMLElement | jQuery

The widget's container. It is an HTML Element or a jQuery Element when you use jQuery.

model

Object

The model data. Available only if you use Knockout.

formOptions

Object

The options of the Form widget.

Default Value: null

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

NOTE

The following Form options cannot be specified using formOptions:

See Also

onCellClick

A function that is executed when a cell is clicked or tapped. Executed before onRowClick.

Type:

Function

|

String

Function parameters:
e:

Object

Information about the event that caused the function's execution.

Object structure:
Name Type Description
component

TreeList

The widget's instance.

element

HTMLElement | jQuery

The widget's container. It is an HTML Element or a jQuery Element when you use jQuery.

model

Object

The model data. Available only if you use Knockout.

jQueryEvent

jQuery.Event

Use 'event' instead.

The jQuery event that caused the function's execution. Deprecated in favor of the event field.

event

Event (jQuery or EventObject)

The event that caused the function's execution. It is a dxEvent or a jQuery.Event when you use jQuery.

data

Object

The data of the row to which the cell belongs. Available if the rowType is "data", "detail" or "detailAdaptive".

key any

The row's key. Available if the rowType is "data", "detail" or "detailAdaptive".
For plain data, the key value depends on the keyExpr option. For hierarchical data, the key is generated automatically or set in the underlying Store of the data source.

value any

The cell's raw value. Available if the rowType is "data".

displayValue any

The cell's displayed value. Available if the rowType is "data".
Differs from the value field only when the cell belongs to the lookup column.

text

String

The cell's formatted value converted to a string. Available if the rowType is "data".

columnIndex

Number

The index of the column to which the cell belongs.

column

Object

This column's configuration.

rowIndex

Number

The index of the row to which the cell belongs. Refer to Column and Row Indexes for more information.

rowType

String

The row's type.

cellElement

HTMLElement | jQuery

The cell's container. It is an HTML Element or a jQuery Element when you use jQuery.

row

TreeList Row

The row properties. Available if the rowType is "data", "detail" or "detailAdaptive".

Default Value: null

onCellHoverChanged

A function that is executed after the pointer enters or leaves a cell.

Type:

Function

Function parameters:
e:

Object

Information about the event that caused the function's execution.

Object structure:
Name Type Description
component

TreeList

The widget's instance.

element

HTMLElement | jQuery

The widget's container. It is an HTML Element or a jQuery Element when you use jQuery.

model

Object

The model data. Available only if you use Knockout.

eventType

String

Indicates whether the pointer entered or left the cell. Can be either "mouseover" or "mouseout".

data

Object

The data of the row to which the cell belongs. Available if the rowType is "data", "detail" or "detailAdaptive".

key any

The row's key. Available if the rowType is "data", "detail" or "detailAdaptive".
For plain data, the key value depends on the keyExpr option. For hierarchical data, the key is generated automatically or set in the underlying Store of the data source.

value any

The cell's raw value. Available if the rowType is "data".

text

String

The cell's formatted value converted to a string. Available if the rowType is "data".

displayValue any

The cell's displayed value. Available if the rowType is "data".
Differs from the value field only when the cell belongs to the lookup column.

columnIndex

Number

The index of the column to which the cell belongs.

rowIndex

Number

The index of the row to which the cell belongs. Refer to Column and Row Indexes for more information.

column

TreeList Column

This column's configuration.

rowType

String

The row's type.

cellElement

HTMLElement | jQuery

The cell's container. It is an HTML Element or a jQuery Element when you use jQuery.

row

TreeList Row

The row properties. Available if the rowType is "data", "detail" or "detailAdaptive".

Default Value: null

To identify whether the pointer has entered or left the cell, check the eventType field's value.

onCellPrepared

A function that is executed after a grid cell is created.

Type:

Function

Function parameters:
e:

Object

Information about the event that caused the function's execution.

Object structure:
Name Type Description
component

TreeList

The widget's instance.

element

HTMLElement | jQuery

The widget's container. It is an HTML Element or a jQuery Element when you use jQuery.

model

Object

The model data. Available only if you use Knockout.

data

Object

The data of the row to which the cell belongs. Available if the rowType is "data", "detail" or "detailAdaptive".

key any

The row's key. Available if the rowType is "data", "detail" or "detailAdaptive".
For plain data, the key value depends on the keyExpr option. For hierarchical data, the key is generated automatically or set in the underlying Store of the data source.

value any

The cell's raw value. Available if the rowType is "data".

displayValue any

The cell's displayed value. Available if the rowType is "data".
Differs from the value field only when the cell belongs to the lookup column.

text

String

The cell's formatted value converted to a string. Available if the rowType is "data".

columnIndex

Number

The index of the column to which the cell belongs.

column

TreeList Column

This column's configuration.

rowIndex

Number

The row's index. Refer to Column and Row Indexes for more information.

rowType

String

The row's type.

row

TreeList Row

The row properties. Available if the rowType is "data", "detail" or "detailAdaptive".

isSelected

Boolean

Indicates whether the row is selected. Available if rowType is "data" or "detail".

isExpanded

Boolean

Indicates whether the row is expanded or collapsed. Available if rowType is "data" or "detail".

cellElement

HTMLElement | jQuery

The cell's container. It is an HTML Element or a jQuery Element when you use jQuery.

Default Value: null

See Also

onContentReady

A function that is executed when the widget's content is ready and each time the content is changed.

Type:

Function

Function parameters:
e:

Object

Information about the event.

Object structure:
Name Type Description
component

TreeList

The widget's instance.

element

HTMLElement | jQuery

The widget's container. It is an HTML Element or a jQuery Element when you use jQuery.

model

Object

The model data. Available only when using Knockout.

Default Value: null

onContextMenuPreparing

A function that is executed before the context menu is rendered.

Type:

Function

Function parameters:
e:

Object

Information about the event that caused the function's execution.

Object structure:
Name Type Description
component

TreeList

The widget's instance.

element

HTMLElement | jQuery

The widget's container. It is an HTML Element or a jQuery Element when you use jQuery.

model

Object

The model data. Available only if you use Knockout.

items

Array<Object>

Items to be displayed in the context menu. Their structure is described in the Default Item Template section.

target

String

The name of the element on which the context menu is invoked: "header", "content" or "footer". This field is read-only.

targetElement

HTMLElement | jQuery

This element's container. It is an HTML Element or a jQuery Element when you use jQuery.

columnIndex

Number

The index of the column on which the context menu is invoked.

column

TreeList Column

This column's configuration.

rowIndex

Number

The index of the row on which the context menu is invoked. Refer to Column and Row Indexes for more information.

row

TreeList Row

The row properties.

Default Value: null

The following code shows how you can customize the context menu using this function:

jQuery
JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        // ... 
        onContextMenuPreparing: function(e) { 
            if (e.target == "header" && e.columnIndex == 0) {
                e.items.push({
                    text: "Item Text",
                    onItemClick: function() {
                        // ...
                    }
                });
            } 
        }
    });
});
Angular
TypeScript
HTML
import { DxTreeListModule } from "devextreme-angular";
// ...
export class AppComponent {
    onContextMenuPreparing (e) { 
        if (e.target == "header" && e.columnIndex == 0) {
            e.items.push({
                text: "Item Text",
                onItemClick: function() {
                    // ...
                }
            });
        } 
    }
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})
<dx-tree-list ...
    (onContextMenuPreparing)="onContextMenuPreparing($event)">
</dx-tree-list>

onDataErrorOccurred

A function that is executed when an error occurs in the data source.

Type:

Function

Function parameters:
e:

Object

Information on the occurred error.

Object structure:
Name Type Description
component

TreeList

The widget's instance.

element

HTMLElement | jQuery

The widget's container. It is an HTML Element or a jQuery Element when you use jQuery.

model

Object

The model data. Available only if you use Knockout.

error

JavaScript Error Object

The standard Error object that defines the error.

Default Value: null

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

onDisposing

A function that is executed before the widget is disposed of.

Type:

Function

Function parameters:
e:

Object

Information about the event.

Object structure:
Name Type Description
component

TreeList

The widget's instance.

element

HTMLElement | jQuery

The widget's container. It is an HTML Element or a jQuery Element when you use jQuery.

model

Object

The model data. Available only if you use Knockout.

Default Value: null

onEditingStart

A function that is executed before a cell or row switches to the editing state.

Type:

Function

Function parameters:
e:

Object

Information about the event that caused the function's execution.

Object structure:
Name Type Description
component

TreeList

The widget's instance.

element

HTMLElement | jQuery

The widget's container. It is an HTML Element or a jQuery Element when you use jQuery.

model

Object

The model data. Available only if Knockout is used.

data

Object

The data of the row to be edited.

key any

The row's key.
The key of an added but not yet saved row is undefined.

cancel

Boolean

Allows you to cancel row editing.

column

Object

The configuration of the column whose cell is switching to the editing state. Available in "cell" or "batch" editing mode.

Default Value: null

In cell or batch editing mode, this function is executed while rendering cells of columns whose showEditorAlways option is set to true.

onEditorPrepared

A function that is executed after an editor is created.

Type:

Function

Function parameters:
options:

Object

Information about the event that caused the function's execution.

Object structure:
Name Type Description
component

TreeList

The widget's instance.

element

HTMLElement | jQuery

The widget's container. It is an HTML Element or a jQuery Element when you use jQuery.

model

Object

The model data. Available only if you use Knockout.

parentType

String

The editor's location. One of "dataRow", "filterRow", "headerRow" or "searchPanel".

value any

The editor's value.

setValue(newValue, newText) any

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

updateValueTimeout

Number

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

width

Number

The editor's width; equals null for all editors except for those whose parentType equals "searchPanel".

disabled

Boolean

Indicates whether the editor is disabled.

rtlEnabled

Boolean

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

editorElement

HTMLElement | jQuery

The editor's container. It is an HTML Element or a jQuery Element when you use jQuery.

readOnly

Boolean

Indicates whether the editor is read-only.

dataField

String

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

row

TreeList Row

The properties of the row the editor belongs to.

Default Value: null

Numerous TreeList elements are based on editors: the search panel is a text box, the filter row uses text boxes, calendars, and select boxes, and so on. This function allows you to add custom CSS classes to those default editors. To change their configuration or substitute them for other editors, use the onEditorPreparing function.

NOTE
This function is not executed for cells that use the editCellTemplate.

onEditorPreparing

A function that is executed before an editor is created.

Type:

Function

Function parameters:
e:

Object

Information about the event that caused the function's execution.

Object structure:
Name Type Description
component

TreeList

The widget's instance.

element

HTMLElement | jQuery

The widget's container. It is an HTML Element or a jQuery Element when you use jQuery.

model

Object

The model data. Available only if you use Knockout.

parentType

String

The editor's location. One of "dataRow", "filterRow", "headerRow" or "searchPanel".

value any

The editor's value.

setValue(newValue, newText) any

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

updateValueTimeout

Number

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

width

Number

The editor's width; equals null for all editors except for those whose parentType equals "searchPanel".

disabled

Boolean

Indicates whether the editor is disabled.

rtlEnabled

Boolean

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

cancel

Boolean

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

editorElement

HTMLElement | jQuery

The editor's container. It is an HTML Element or a jQuery Element when you use jQuery.

readOnly

Boolean

Indicates whether the editor is read-only.

editorName

String

Allows you to change the editor. Accepts names of DevExtreme widgets only, for example, "dxTextBox".
Import a new editor's module when using DevExtreme modules.

editorOptions

Object

Gets and sets the editor configuration.

dataField

String

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

row

TreeList Row

The properties of the row editor belongs to.

Default Value: null

Numerous TreeList elements are based on editors: the search panel is a text box, the filter row uses text boxes, calendars, and select boxes, and so on. Use this function to customize those default editors or substitute them for other editors.

In the following code, a default editor is replaced with the DevExtreme TextArea widget. Note that the widget's onValueChanged function is overridden, and its declaration ends with the setValue(newValue, newText) method's call. This method updates the cell value.

jQuery
JavaScript
$(function() {
    $("#treeList").dxTreeList({
        // ...
        onEditorPreparing: function(e) {
            if (e.dataField == "description") {
                e.editorName = "dxTextArea"; 
                e.editorOptions.showClearButton = true;
                e.editorOptions.onValueChanged = (event) => {
                    var value = event.value;
                    e.setValue(value.toLowerCase()); 
                }
            }
        }
    });
});
Angular
TypeScript
HTML
import { DxTreeListModule } from "devextreme-angular";
// ...
export class AppComponent {
    onEditorPreparing (e) { 
        if (e.dataField == "description") {
            e.editorName = "dxTextArea"; 
            e.editorOptions.showClearButton = true;
            e.editorOptions.onValueChanged = (event) => {
                let value = event.value;
                e.setValue(value.toLowerCase()); 
            }
        }
    }
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})
<dx-tree-list ...
    (onEditorPreparing)="onEditorPreparing($event)">
</dx-tree-list>

The following code shows how to replace a default editor with a non-DevExtreme editor (an HTML checkbox in this case):

jQuery
JavaScript
$(function() {
    $("#treeList").dxTreeList({
        // ...
        onEditorPreparing: function(e) {
            if(e.dataField === "completed") {
                e.cancel = true; // Cancels creating the default editor
                $('<input type="checkbox">')
                    .prop("checked", e.value)
                    .on("change", (event) => {
                        e.setValue(event.target.checked); 
                    })
                    .appendTo(e.editorElement);
            }
        }
    });
});
Angular
TypeScript
HTML
import { DxTreeListModule } from "devextreme-angular";
// ...
export class AppComponent {
    onEditorPreparing (e) { 
        if(e.dataField === "completed") {
            e.cancel = true; // Cancels creating the default editor
            let checkbox = document.createElement("INPUT");
            checkbox.setAttribute("type", "checkbox");
            checkbox.setAttribute("checked", e.value);
            checkbox.addEventListener("change", (event) => {
                e.setValue(event.target.checked);
            });
            e.editorElement.appendChild(checkbox);
        }
    }
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule
    ],
    // ...
})
<dx-tree-list ...
    (onEditorPreparing)="onEditorPreparing($event)">
</dx-tree-list>
NOTE
This function is not executed for cells that use the editCellTemplate.
See Also

onInitialized

A function that is executed only once, after the widget is initialized.

Type:

Function

Function parameters:
e:

Object

Information about the event.

Object structure:
Name Type Description
component

TreeList

The widget's instance.

element

HTMLElement | jQuery

The widget's container. It is an HTML Element or a jQuery Element when you use jQuery.

Default Value: null

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

onInitNewRow

A function that is executed before a new row is added to the widget.

Type:

Function

Function parameters:
e:

Object

Information about the event that caused the function's execution.

Object structure:
Name Type Description
component

TreeList

The widget's instance.

element

HTMLElement | jQuery

The widget's container. It is an HTML Element or a jQuery Element when you use jQuery.

model

Object

The model data. Available only if you use Knockout.

data

Object

The data of the inserted row; initially empty.

Default Value: null

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

onKeyDown

A function that is executed when the widget is in focus and a key has been pressed down.

Type:

Function

Function parameters:
e:

Object

Information about the event that caused the function's execution.

Object structure:
Name Type Description
component

TreeList

The widget's instance.

element

HTMLElement | jQuery

The widget's container. It is an HTML Element or a jQuery Element when you use jQuery.

jQueryEvent

jQuery.Event

Use 'event' instead.

The jQuery event that caused the function's execution. Deprecated in favor of the event field.

event

Event (jQuery or EventObject)

The event that caused the function's execution. It is a dxEvent or a jQuery.Event when you use jQuery.

handled

Boolean

Indicates whether the widget has already handled this event.

Default Value: null

onNodesInitialized

A function that is executed after the loaded nodes are initialized.

Type:

Function

Function parameters:
e:

Object

Information about the event that caused the function's execution.

Object structure:
Name Type Description
component

TreeList

The widget's instance.

element

HTMLElement | jQuery

The widget's container. It is an HTML Element or a jQuery Element when you use jQuery.

model

Object

The model data. Available only if you use Knockout.

root

TreeList Node

The root node.

Default Value: null

Use this function to modify the node fields. You can traverse the tree using the forEachNode(callback) method or implement your custom algorithm. Within this algorithm, start traversing from the root node, which is available via the function parameter's root field. Every node, including the root one, provides access to its child nodes in the children field, which allows traversing the whole tree.

onOptionChanged

A function that is executed after a widget option is changed.

Type:

Function

Function parameters:
e:

Object

Information about the event.

Object structure:
Name Type Description
name

String

The option's short name.

model

Object

The model data. Available only if you use Knockout.

element

HTMLElement | jQuery

The widget's container. It is an HTML Element or a jQuery Element when you use jQuery.

component

TreeList

The widget's instance.

fullName

String

The option's full name.

value any

The option's new value.

Default Value: null

onRowClick

A function that is executed when a grid row is clicked or tapped.

Type:

Function

|

String

Function parameters:
e:

Object

Information about the event that caused the function's execution.

Object structure:
Name Type Description
component

TreeList

The widget's instance.

element

HTMLElement | jQuery

The widget's container. It is an HTML Element or a jQuery Element when you use jQuery.

model

Object

The model data. Available only if you use Knockout.

jQueryEvent

jQuery.Event

Use 'event' instead.

The jQuery event that caused the function's execution. Deprecated in favor of the event field.

event

Event (jQuery or EventObject)

The event that caused the function's execution. It is a dxEvent or a jQuery.Event when you use jQuery.

data

Object

The row's data.

key any

The row's key. Available if the rowType is "data", "detail" or "detailAdaptive".
For plain data, the key value depends on the keyExpr option. For hierarchical data, the key is generated automatically or set in the underlying Store of the data source.

values

Array<Object>

Values displayed in the row cells.

columns

Array<Object>

All column configurations.

rowIndex

Number

The row's index. Refer to Column and Row Indexes for more information.

rowType

String

The row's type.

isSelected

Boolean

Indicates whether the row is selected. Available if rowType is "data" or "detail".

isExpanded

Boolean

Indicates whether the row is expanded or collapsed. Available if rowType is "data" or "detail".

rowElement

HTMLElement | jQuery

The row's container. It is an HTML Element or a jQuery Element when you use jQuery.

handled

Boolean

Indicates whether internal widget functions have already handled the event.

Default Value: null

Prior to this function, the widget executes the onCellClick function and sometimes internal functions. You can use the handled field to check whether internal functions were executed.

NOTE
When the clicked row is in the editing state or switches to this state, the onRowClick function is not executed. Instead, specify the onCellClick function.

onRowCollapsed

A function that is executed after a row is collapsed.

Type:

Function

Function parameters:
e:

Object

Information about the event that caused the function's execution.

Object structure:
Name Type Description
component

TreeList

The widget's instance.

element

HTMLElement | jQuery

The widget's container. It is an HTML Element or a jQuery Element when you use jQuery.

model

Object

The model data. Available only if you use Knockout.

key any

The key of the row.

Default Value: null

onRowCollapsing

A function that is executed before a row is collapsed.

Type:

Function

Function parameters:
e:

Object

Information about the event that caused the function's execution.

Object structure:
Name Type Description
component

TreeList

The widget's instance.

element

HTMLElement | jQuery

The widget's container. It is an HTML Element or a jQuery Element when you use jQuery.

model

Object

The model data. Available only if you use Knockout.

key any

The key of the row.

cancel

Boolean

Allows you to cancel row collapsing.

Default Value: null

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

onRowExpanded

A function that is executed after a row is expanded.

Type:

Function

Function parameters:
e:

Object

Information about the event that caused the function's execution.

Object structure:
Name Type Description
component

TreeList

The widget's instance.

element

HTMLElement | jQuery

The widget's container. It is an HTML Element or a jQuery Element when you use jQuery.

model

Object

The model data. Available only if you use Knockout.

key any

The key of the row.

Default Value: null

onRowExpanding

A function that is executed before a row is expanded.

Type:

Function

Function parameters:
e:

Object

Information about the event that caused the function's execution.

Object structure:
Name Type Description
component

TreeList

The widget's instance.

element

HTMLElement | jQuery

The widget's container. It is an HTML Element or a jQuery Element when you use jQuery.

model

Object

The model data. Available only if you use Knockout.

key any

The key of the group or master row.

cancel

Boolean

Allows you to cancel row expansion.

Default Value: null

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

onRowInserted

A function that is executed after a new row has been inserted into the data source.

Type:

Function

Function parameters:
e:

Object

Information about the event that caused the function's execution.

Object structure:
Name Type Description
component

TreeList

The widget's instance.

element

HTMLElement | jQuery

The widget's container. It is an HTML Element or a jQuery Element when you use jQuery.

model

Object

The model data. Available only if you use Knockout.

data

Object

The data of the row.

key any

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

error

JavaScript Error Object

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

Default Value: null

NOTE
In batch editing mode, if several rows have been inserted, this function will be executed for each row individually.

onRowInserting

A function that is executed before a new row is inserted into the data source.

Type:

Function

Function parameters:
e:

Object

Information about the event that caused the function's execution.

Object structure:
Name Type Description
component

TreeList

The widget's instance.

element

HTMLElement | jQuery

The widget's container. It is an HTML Element or a jQuery Element when you use jQuery.

model

Object

The model data. Available only if you use Knockout.

data

Object

The data of the row that should be inserted.

cancel

Boolean

|

Promise<void> (jQuery or native)

true, a Promise resolved with true, or a rejected Promise stops row insertion.
false or a Promise resolved with false or undefined continues row insertion.

Default Value: null

NOTE
In batch editing mode, this function is executed for each row individually if several rows should be inserted.

The following code shows how to use the function parameter's cancel field to prevent or continue row insertion. In this code, a Promise is assigned to this field. Row insertion continues if row data validation on the server succeeds (the Promise is resolved); otherwise, row insertion is prevented (the Promise is rejected).

jQuery
JavaScript
$(function(){
    $("#treeListContainer}").dxTreeList({
        // ...
        onRowInserting: function(e) {
            var d = $.Deferred();
            $.getJSON("https://url/to/your/validation/service", JSON.stringify(e.data))
                .then((result) => !result.errorText ? d.resolve() : d.reject(result.errorText))
                .fail(() => d.reject())
            e.cancel = d.promise();
        }
    })
})
Angular
TypeScript
HTML
import { DxTreeListModule } from "devextreme-angular";
import { HttpClient, HttpClientModule, HttpParams } from "@angular/common/http";
import "rxjs/add/operator/toPromise";
// ...
export class AppComponent {
    constructor(private httpClient: HttpClient) { /*...*/}
    onRowInserting(e) {
        let params = new HttpParams({ fromString: JSON.stringify(e.data) });
        let result = this.httpClient.get("https://url/to/your/validation/service", { params: params })
            .toPromise();
        e.cancel = new Promise((resolve, reject) => {
            result.then((validationResult) => {
                !validationResult.errorText ? resolve() : reject(validationResult.errorText)
            })
            .catch(() => reject());
        })    
    }
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule,
        HttpClientModule
    ],
    // ...
})
<dx-tree-list ... 
    (onRowInserting)="onRowInserting($event)">
</dx-tree-list>

onRowPrepared

A function that is executed after a row is created.

Type:

Function

Function parameters:
e:

Object

Information about the event that caused the function's execution.

Object structure:
Name Type Description
component

TreeList

The widget's instance.

element

HTMLElement | jQuery

The widget's container. It is an HTML Element or a jQuery Element when you use jQuery.

model

Object

The model data. Available only if you use Knockout.

data

Object

The row's data. Available if the rowType is "data", "detail" or "detailAdaptive".

key any

The row's key. Available if the rowType is "data", "detail" or "detailAdaptive".
For plain data, the value of the key depends on the keyExpr option. For hierarchical data, the key is generated automatically or set in the underlying Store of the data source.

values

Array<Object>

Values displayed in the row cells.

columns

Array<TreeList Column>

All column configurations.

rowIndex

Number

The row's index. Refer to Column and Row Indexes for more information.

rowType

String

The row's type.

isSelected

Boolean

Indicates whether the row is selected. Available if rowType is "data" or "detail".

isExpanded

Boolean

Indicates whether the row is expanded or collapsed. Available if rowType is "data" or "detail".

rowElement

HTMLElement | jQuery

The row's container. It is an HTML Element or a jQuery Element when you use jQuery.

Default Value: null

onRowRemoved

A function that is executed after a row has been removed from the data source.

Type:

Function

Function parameters:
e:

Object

Information about the event that caused the function's execution.

Object structure:
Name Type Description
component

TreeList

The widget's instance.

element

HTMLElement | jQuery

The widget's container. It is an HTML Element or a jQuery Element when you use jQuery.

model

Object

The model data. Available only if you use Knockout.

data

Object

The data of the row.

key any

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

error

JavaScript Error Object

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

Default Value: null

NOTE
In batch editing mode, if several rows have been removed, this function will be executed for each row individually.

onRowRemoving

A function that is executed before a row is removed from the data source.

Type:

Function

Function parameters:
e:

Object

Information about the event that caused the function's execution.

Object structure:
Name Type Description
component

TreeList

The widget's instance.

element

HTMLElement | jQuery

The widget's container. It is an HTML Element or a jQuery Element when you use jQuery.

model

Object

The model data. Available only if you use Knockout.

data

Object

The data of the row that should be removed.

key any

The row's key.

cancel

Boolean

|

Promise<void> (jQuery or native)

true, a Promise resolved with true, or a rejected Promise stops row removal.
false or a Promise resolved with false or undefined continues row removal.

Default Value: null

NOTE
In batch editing mode, this function is executed for each row individually if several rows should be removed.

The following code shows how to use the function parameter's cancel field to prevent or continue row removal. In this code, a Promise is assigned to this field. Row removal continues if checks on the server succeed (the Promise is resolved); otherwise, row removal is prevented (the Promise is rejected).

jQuery
JavaScript
$(function(){
    $("#treeListContainer}").dxTreeList({
        // ...
        onRowRemoving: function(e) {
            var d = $.Deferred();
            $.getJSON("https://url/to/your/validation/service", JSON.stringify(e.data))
                .then((result) => !result.errorText ? d.resolve() : d.reject(result.errorText))
                .fail(() => d.reject())
            e.cancel = d.promise();
        }
    })
})
Angular
TypeScript
HTML
import { DxTreeListModule } from "devextreme-angular";
import { HttpClient, HttpClientModule, HttpParams } from "@angular/common/http";
import "rxjs/add/operator/toPromise";
// ...
export class AppComponent {
    constructor(private httpClient: HttpClient) { /*...*/}
    onRowRemoving(e) {
        let params = new HttpParams({ fromString: JSON.stringify(e.data) });
        let result = this.httpClient.get("https://url/to/your/validation/service", { params: params })
            .toPromise();
        e.cancel = new Promise((resolve, reject) => {
            result.then((validationResult) => {
                !validationResult.errorText ? resolve() : reject(validationResult.errorText)
            })
            .catch(() => reject());
        })    
    }
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule,
        HttpClientModule
    ],
    // ...
})
<dx-tree-list ... 
    (onRowRemoving)="onRowRemoving($event)">
</dx-tree-list>

onRowUpdated

A function that is executed after a row has been updated in the data source.

Type:

Function

Function parameters:
e:

Object

Information about the event that caused the function's execution.

Object structure:
Name Type Description
component

TreeList

The widget's instance.

element

HTMLElement | jQuery

The widget's container. It is an HTML Element or a jQuery Element when you use jQuery.

model

Object

The model data. Available only if you use Knockout.

data

Object

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

key any

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

error

JavaScript Error Object

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

Default Value: null

NOTE
In batch editing mode, if several rows have been updated, this function will be executed for each row individually.

onRowUpdating

A function that is executed before a row is updated in the data source.

Type:

Function

Function parameters:
e:

Object

Information about the event that caused the function's execution.

Object structure:
Name Type Description
component

TreeList

The widget's instance.

element

HTMLElement | jQuery

The widget's container. It is an HTML Element or a jQuery Element when you use jQuery.

model

Object

The model data. Available only if you use Knockout.

oldData

Object

The row's old data.

newData

Object

The row's updated data.

key any

The row's key.

cancel

Boolean

|

Promise<void> (jQuery or native)

true, a Promise resolved with true, or a rejected Promise stops row updating.
false or a Promise resolved with false or undefined continues row updating.

Default Value: null

NOTE
In batch editing mode, this function is executed for each row individually if several rows should be updated.

The following code shows how to use the function parameter's cancel field to prevent or continue row updating. In this code, a Promise is assigned to this field. Row updating continues if row data validation on the server succeeds (the Promise is resolved); otherwise, row updating is prevented (the Promise is rejected).

jQuery
JavaScript
$(function(){
    $("#treeListContainer}").dxTreeList({
        // ...
        onRowUpdating: function(e) {
            var d = $.Deferred();
            $.getJSON("https://url/to/your/validation/service", JSON.stringify(e.data))
                .then((result) => !result.errorText ? d.resolve() : d.reject(result.errorText))
                .fail(() => d.reject())
            e.cancel = d.promise();
        }
    })
})
Angular
TypeScript
HTML
import { DxTreeListModule } from "devextreme-angular";
import { HttpClient, HttpClientModule, HttpParams } from "@angular/common/http";
import "rxjs/add/operator/toPromise";
// ...
export class AppComponent {
    constructor(private httpClient: HttpClient) { /*...*/}
    onRowUpdating(e) {
        let params = new HttpParams({ fromString: JSON.stringify(e.data) });
        let result = this.httpClient.get("https://url/to/your/validation/service", { params: params })
            .toPromise();
        e.cancel = new Promise((resolve, reject) => {
            result.then((validationResult) => {
                !validationResult.errorText ? resolve() : reject(validationResult.errorText)
            })
            .catch(() => reject());
        })    
    }
}
@NgModule({
    imports: [
        // ...
        DxTreeListModule,
        HttpClientModule
    ],
    // ...
})
<dx-tree-list ... 
    (onRowUpdating)="onRowUpdating($event)">
</dx-tree-list>

onRowValidating

A function that is executed after cells in a row are validated against validation rules.

Type:

Function

Function parameters:
e:

Object

Information about the event that caused the function's execution.

Object structure:
Name Type Description
component

TreeList

The widget's instance.

element

HTMLElement | jQuery

The widget's container. It is an HTML Element or a jQuery Element when you use jQuery.

model

Object

The model data. Available only if you use Knockout.

brokenRules

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

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

isValid

Boolean

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

key any

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

newData

Object

The data of the validated row after changes.

oldData

Object

The data of the validated row before changes.

errorText

String

An error message to be displayed.

Default Value: null

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

NOTE
In batch editing mode, if changes in several rows are committed simultaneously, this function will be executed for each row.

onSelectionChanged

A function that is executed after selecting a row or clearing its selection.

Type:

Function

Function parameters:
e:

Object

Information about the event that caused the function's execution.

Object structure:
Name Type Description
component

TreeList

The widget's instance.

element

HTMLElement | jQuery

The widget's container. It is an HTML Element or a jQuery Element when you use jQuery.

model

Object

The model data. Available only if you use Knockout.

currentSelectedRowKeys

Array<any>

The keys of the rows that have been selected.

currentDeselectedRowKeys

Array<any>

The keys of the rows whose selection has been cleared.

selectedRowKeys

Array<any>

The keys of all selected rows.

selectedRowsData

Array<Object>

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

Default Value: null

onToolbarPreparing

A function that is executed before the toolbar is created.

Type:

Function

Function parameters:
e:

Object

Information about the event that caused the function's execution.

Object structure:
Name Type Description
component

TreeList

The widget's instance.

element

HTMLElement | jQuery

The widget's container. It is an HTML Element or a jQuery Element when you use jQuery.

model

Object

The model data. Available only if you use Knockout.

toolbarOptions

Toolbar Configuration

The options of the toolbar.

Default Value: null

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

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

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

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

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

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

pager

Configures the pager.

Type:

Object

The pager is an element that allows users to navigate through pages and change their size at runtime. The pager consists of the page navigator and several optional elements: the page size selector, navigation buttons, and page information.

DevExtreme HTML5 JavaScript jQuery Angular Knockout Widget TreeList Pager

View Demo

See Also

paging

Configures paging.

Type:

Object

Paging allows the widget to render rows by pages instead of rendering them at once. To enable paging, set the paging.enabled option to true.

View Demo

See Also

parentIdExpr

Specifies which data field provides parent keys.

Type:

String

|

Function

Default Value: 'parentId'

See Also

remoteOperations

Notifies the TreeList of the server's data processing operations. Applies only if data has a plain structure.

Type:

Object

Server-side data processing improves the widget's performance on large datasets. When the server does not implement particular operations (and/or the corresponding remoteOperations fields are false) they are executed on the client. Note that the widget may send queries to the server while executing a client-side operation.

The following table lists the possible remoteOperations configurations and the operations the server should implement. The server should also implement additional operations depending on the used widget functionality.

Setting Required server-side operations Additional server-side operations
remoteOperations: { filtering: true } filtering -
remoteOperations: { sorting: true } sorting filtering*
remoteOperations: { grouping: true } grouping, filtering sorting*
* - If this functionality is used in the widget.
NOTE
Filtering and sorting are performed on the server side for the ODataStore, but you can change them to the client side by setting the corresponding remoteOperations fields to false. Other operations are always client-side.

When operations are performed on the server side, the TreeList does not support:

Web API Service Demo

See Also

renderAsync

Specifies whether to render the filter row, command columns, and columns with showEditorAlways set to true after other elements.

Type:

Boolean

Default Value: false

See Also

rootValue

Specifies the root node's identifier. Applies if dataStructure is "plain".

Type:

Object

Default Value: 0

rowAlternationEnabled

Specifies whether rows should be shaded differently.

Type:

Boolean

Default Value: false

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

rtlEnabled

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

Type:

Boolean

Default Value: false

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

JavaScript
DevExpress.config({
    rtlEnabled: true
});
See Also

scrolling

Configures scrolling.

Type:

Object

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

See Also

searchPanel

Configures the search panel.

Type:

Object

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

DevExtreme HTML5 JavaScript jQuery Angular Knockout Widget TreeList SearchPanel

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

View Demo

See Also

selectedRowKeys

Allows you to select rows or determine which rows are selected.

Type:

Array<any>

Raised Events: onSelectionChanged

selection

Configures runtime selection.

Type:

Object

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

See Also

showBorders

Specifies whether the outer borders of the widget are visible.

Type:

Boolean

Default Value: false

showColumnHeaders

Specifies whether column headers are visible.

Type:

Boolean

Default Value: true

See Also

showColumnLines

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

Type:

Boolean

Default Value: true, false (Material)

NOTE
If you use the Android or iOS theme, specifying this option doesn't affect anything. These themes avoid displaying column lines in order to provide a native look for the widget. In case you still require the column lines to be displayed, choose another theme.

showRowLines

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

Type:

Boolean

Default Value: false, true (iOS, Material)

sorting

Configures runtime sorting.

Type:

Object

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

DevExtreme HTML5 JavaScript jQuery Angular Knockout Widget TreeList Sorting

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

DevExtreme HTML5 JavaScript jQuery Angular Knockout Widget TreeList Sorting

Note that rows are sorted within their hierarchical level.

View Demo

See Also

stateStoring

Configures state storing.

Type:

Object

State storing enables the widget to save applied settings and restore them the next time the widget is loaded. These settings include filtering, sorting, column order and width, selection, and others. Assign true to the stateStoring.enabled option to enable this functionality.

NOTE
The expanded row keys are not saved if the autoExpandAll is set to true.

View Demo

See Also

tabIndex

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

Type:

Number

Default Value: 0

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

twoWayBindingEnabled

Specifies whether to enable two-way data binding.

Type:

Boolean

Default Value: true

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

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

visible

Specifies whether the widget is visible.

Type:

Boolean

Default Value: true

width

Specifies the widget's width.

Type:

Number

|

String

|

Function

Return Value:

Number

|

String

The widget's width.

Default Value: undefined

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

  • Number
    The width in pixels.

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

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

    JavaScript
    width: function() {
        return window.innerWidth / 1.5;
    }

wordWrapEnabled

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

Type:

Boolean

Default Value: false