Configuration

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 Widget TreeList ColumnChooser

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 Widget TreeList ColumnFixing

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

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

When displaying the widget in your app, you may want to use different layouts for different screen sizes. While desktop monitors provide enough space to display all columns, mobile screens do not. You can enable the widget to hide certain columns automatically if they do not fit into the screen size by assigning true to the columnHidingEnabled option. Information from hidden columns is available in the adaptive detail row.

When hiding columns, the widget uses the following principles:

  1. The lower the hidingPriority, the higher the probability that the widget hides this column. When you do not specify hiding priorities, their values ascend from right to left beginning with 0. This means that the widget hides the rightmost columns at first.
  2. If the width of a column is specified, this column is hidden only if it exceeds the width of the widget.
  3. If the width of a column is not specified, this column is hidden only if its content overflows it.
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.

columns[]

Configures columns.

Type: Array
Default Value: undefined

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.

JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        columns: [{
            dataField: "Title",
            caption: "Position"
        }, {
            dataField: "FullName",
            width: 300
        }, 
            "CompanyName",
            "City"
        ]
    });
});
See Also

customizeColumns

Customizes columns after they are created.

Type: function(columns)
Function parameters:
columns: Array
Configurations of columns.

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

JavaScript
$(function(){
    $("#treeList").dxTreeList({
        // ...
        customizeColumns: function (columns) {
            columns[0].width = 100;
            columns[1].width = 210;
        }
    })
});

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
    A URL to JSON data or to a service returning data in JSON format.

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

    NOTE
    If you use data mapping, features like selection may work incorrectly. We recommend using calculated columns instead of mapping.

The widget cannot track changes made in the data source by a third party. 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 the serialization format for date-time values.

Type: String

If you do not set the dataSource option at design time, the widget cannot detect the format of date-time values automatically. In this case, specify the dateSerializationFormat option. You can also do this to serialize date-time values to a specific format.

The following formats are supported.

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

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

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

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

Note that this option only applies if the forceIsoDateParsing field of the global configuration object is set to true.

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.

Watch Video

See Also

elementAttr

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

Type: Object
Default Value: {}

When you configure this option in an ASP.NET MVC Control, pass a dictionary as shown in the following code.

Razor C#
Razor VB
@(Html.DevExtreme()
    // other widget options
    // ...
    .ElementAttr(new Dictionary<string, object>() {
        { "id", "elementId" },
        { "class", "class-name" },
        // ...
    })
)
@(Html.DevExtreme().WidgetName() _
    .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
Default Value: []

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

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.

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.

See Also

height

Specifies the height of the widget.

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

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

  • Number
    The height of the widget 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 the widget changes its state when a user pauses on it.

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 handler for the adaptiveDetailRowPreparing event. Executed before an adaptive detail row is rendered.

Type: function
Function parameters:
Information about the event.
Object structure:
component: Object
The widget instance.
element: jQuery
The widget's container.
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 handler 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 handler for the cellClick event. Executed after a user clicks a cell.

Type: function(e) |String
Function parameters:
Information about the event.
Object structure:
component: Object
The widget's instance.
element: jQuery
The widget's container.
model: Object
The model data. Available only if you use Knockout.
jQueryEvent: jQuery.Event
The original jQuery event.
data: Object
Data of the row to which the cell belongs. Available if the rowType is 'data', 'detail' or 'detailAdaptive'.
key: any
The row 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 value. Available if the rowType is 'data'.
displayValue: String
The value displayed in the cell. Available if the rowType is 'data'.
Differs from the value field only when the cell belongs to the lookup column.
text: String
The cell value in the string format. Available if the rowType is 'data'.
Use this field to get the value with the applied format.
columnIndex: Number
The index of the column to which the cell belongs.
column: Object
Configuration of this column.
rowIndex: Number
The visible index of the row to which the cell belongs.
rowType: String
cellElement: jQuery
The cell's container.
The row properties. Available if the rowType is 'data', 'detail' or 'detailAdaptive'.
Default Value: null

When using DevExtreme SPA Framework, you can navigate to a specific URL on a click. For this, assign this URL or its anchor part (#) directly to this option.

onCellHoverChanged

A handler for the cellHoverChanged event. Executed after the pointer enters or leaves a cell.

Type: function(e)
Function parameters:
Information about the event.
Object structure:
component: Object
The widget's instance.
element: jQuery
The widget's container.
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
Data of the row to which the cell belongs. Available if the rowType is 'data', 'detail' or 'detailAdaptive'.
key: any
The row 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 value. Available if the rowType is 'data'.
text: String
The cell value in the string format. Available if the rowType is 'data'.
Use to get the value with the applied format.
displayValue: String
The value displayed in the cell. 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 visible index of the row to which the cell belongs.
column: Object
Configuration of the column.
rowType: String
cellElement: jQuery
The cell's container.
The row properties. Available if the rowType is 'data', 'detail' or 'detailAdaptive'.
Default Value: null

onCellPrepared

A handler for the cellPrepared event. Executed after the widget creates a cell.

Type: function(e)
Function parameters:
Information about the event.
Object structure:
component: Object
The widget's instance.
element: jQuery
The widget's container.
model: Object
The model data. Available only if you use Knockout.
data: Object
Data of the row to which the cell belongs. Available if the rowType is 'data', 'detail' or 'detailAdaptive'.
key: any
The key of the row. 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 value. Available if the rowType is 'data'.
displayValue: String
The value displayed in the cell. Available if the rowType is 'data'.
Differs from the value field only when the cell belongs to the lookup column.
text: String
The cell value in the string format. Available if the rowType is 'data'.
Use to get the value with the applied format.
columnIndex: Number
The index of the column to which the cell belongs.
column: Object
Configuration of this column.
rowIndex: Number
The visible index of the row.
rowType: String
The properties of the row. 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: jQuery
The cell's container.
Default Value: null

onContentReady

A handler for the contentReady event. Executed when the widget's content is ready.

Type: function
Function parameters:
Information about the event.
Object structure:
component: Object
The widget's instance.
element: jQuery
The widget's container.
model: Object
The model data. Available only if you use Knockout.
Default Value: null

onContextMenuPreparing

A handler for the contextMenuPreparing event. Executed before a context menu is rendered.

Type: function(e)
Function parameters:
Information about the event.
Object structure:
component: Object
The widget's instance.
element: jQuery
The widget's container.
model: Object
The model data. Available only if you use Knockout.
items: Array
Items to be displayed in the context menu. The structure of items 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: jQuery
This element's container.
columnIndex: Number
The index of the column on which the context menu is invoked.
column: Object
Configuration of this column.
rowIndex: Number
The visible index of the row on which the context menu is invoked.
The row properties.
Default Value: null

This handler allows you to customize the context menu.

JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        // ... 
        onContextMenuPreparing: function(e) { 
            if (e.target == "header" && e.columnIndex == 0) {
                e.items.push({
                    text: "Item Text",
                    onItemClick: function() {
                        // ...
                    }
                });
            } 
        }
    });
});

onDataErrorOccurred

A handler for the dataErrorOccurred event. Executed when an error occurs in the data source.

Type: function
Function parameters:
Information on the occurred error.
Object structure:
component: Object
The widget instance.
element: jQuery
The widget's container.
model: Object
The model data. Available only if you use Knockout.
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 handler, use the error.message field.

onDisposing

A handler for the disposing event. Executed when the widget is removed from the DOM using the remove(), empty(), or html() jQuery methods only.

Type: function
Function parameters:
Information about the event.
Object structure:
component: Object
The widget instance.
element: jQuery
The widget's container.
model: Object
The model data. Available only if you use Knockout.
Default Value: null

onEditingStart

A handler for editingStart. Executed before a cell or row switches to the editing state.

Type: function(e)
Function parameters:
Information about the event.
Object structure:
component: Object
The widget's instance.
element: jQuery
The widget's container.
model: Object
The model data. Available only if Knockout is used.
data: Object
Data of a 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
Configuration of the column whose cell is switching to the editing state. Available in 'cell' or 'batch' editing mode.
Default Value: null

onEditorPrepared

A handler for the editorPrepared event. Executed after an editor is created.

Type: function(options)
Function parameters:
options: Object
Information about the event.
Object structure:
component: Object
The widget's instance.
element: jQuery
The widget's container.
model: Object
The model data. Available only if you use Knockout.
parentType: String
The editor's location. This field can have the following values: 'dataRow', 'filterRow', 'headerRow' or 'searchPanel'.
value: any
The editor value.
setValue(newValue): any
A method that you need to call to change a cell value when the editor value is changed.
updateValueTimeout: Number
A delay between the moment a user finishes typing a filter value and the moment it is applied. Available if parentType is 'filterRow' or 'searchPanel'.
width: Number
The editor width. Has a value only for those editors whose parentType is 'searchPanel', for all others it equals null.
disabled: Boolean
Indicates whether the editor is disabled.
rtlEnabled: Boolean
Indicates whether the editor uses right-to-left representation.
editorElement: jQuery
The editor's container.
readOnly: Boolean
Indicates whether the editor responds to user actions.
dataField: String
The name of the field that provides data for the column to which the editor belongs.
The properties of the row to which the editor belongs.
Default Value: null

Many TreeList elements are based on editors. For example, the search panel is based on a text box, a selection column uses check boxes, etc. You can customize automatically created editors using this handler.

NOTE
For cells that use the editCellTemplate, the onEditorPrepared handler is not executed.

onEditorPreparing

A handler for the editorPreparing event. Executed before an editor is created.

Type: function(e)
Function parameters:
Information about the event.
Object structure:
component: Object
The widget's instance.
element: jQuery
The widget's container.
model: Object
The model data. Available only if you use Knockout.
parentType: String
The editor's location. This field can have the following values: 'dataRow', 'filterRow', 'headerRow' or 'searchPanel'.
value: any
The editor value.
setValue(newValue): any
A method that you should call to change the cell value when the editor value is changed.
updateValueTimeout: Number
A delay between the moment a user finishes typing a filter value and the moment it is applied. Available if parentType is 'filterRow' or 'searchPanel'.
width: Number
The editor width. Has a value only for those editors whose parentType is 'searchPanel', for all others it equals null.
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 creation of the editor.
editorElement: jQuery
The editor's container.
readOnly: Boolean
Indicates whether the editor responds to user actions.
editorName: String
Allows you to change the editor. Accepts only names of DevExtreme widgets.
editorOptions: Object
The editor configuration.
dataField: String
The name of the field that provides data for the column to which the editor belongs.
The properties of the row to which the editor belongs.
Default Value: null

Many TreeList elements are based on editors. For example, the search panel is based on a text box, the selection column uses check boxes, etc. Within this handler, you can customize a default editor or substitute it for another DevExtreme editor. To do the latter, assign the editor's name to the editorName field and then configure the editor in the editorOptions object. If you specify the editor's onValueChanged handler, call the setValue(newValue) method in it to update the cell value.

JavaScript
$(function() {
    $("#treeList").dxTreeList({
        // ...
        onEditorPreparing: function(e) {
            if (e.dataField == "name") {
                e.editorName = "dxTextArea";
                e.editorOptions.showClearButton = true;
                e.editorOptions.onValueChanged = function (e) {
                    var value = e.value;
                    if(value == "") {
                        alert("TextArea is empty");
                        return;
                    }
                    e.setValue(value);
                }
            }
        }
    });
});

If you use a third-party editor, cancel creation of the default editor and then implement your own one. To notify the TreeList of the changed value, call the setValue(newValue) method in the onEditorPreparing handler.

JavaScript
$(function() {
    $("#treeList").dxTreeList({
        // ...
        onEditorPreparing: function(e) {
            if(e.dataField === "hidden") {
                e.cancel = true;
                $('<input type="checkbox">')
                    .prop("checked", e.value)
                    .on("change", function(args) {
                        e.setValue(args.target.checked);
                    })
                    .appendTo(e.editorElement);
            }
        }
    });
});
NOTE
For cells that use the editCellTemplate, the onEditorPreparing handler is not executed.

onInitialized

A handler for the initialized event. Executed only once, after the widget is initialized.

Type: function
Function parameters:
Information about the event.
Object structure:
component: Object
The widget instance.
element: jQuery
The widget's container.
Default Value: null

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

onInitNewRow

A handler for the initNewRow event. Executed before a new row is added to the widget.

Type: function(e)
Function parameters:
Information about the event.
Object structure:
component: Object
The widget instance.
element: jQuery
The widget's container.
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 handler, 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 handler for the keyDown event. Executed when the widget is in focus and a key has been pressed down.

Type: function(e)
Function parameters:
Information about the event.
Object structure:
component: Object
The widget instance.
element: jQuery
The widget's container.
jQueryEvent: jQuery.Event
The original jQuery event.
handled: Boolean
Indicates whether the widget has already handled this event.
Default Value: null

onNodesInitialized

A handler for the nodesInitialized event. Executed after all nodes in the widget are initialized.

Type: function(e)
Function parameters:
Information about the event.
Object structure:
component: Object
The widget's instance.
element: jQuery
The widget's container.
model: Object
The model data. Available only if you use Knockout.
The root node.
Default Value: null

This handler is executed once - at the beginning of the widget's lifetime. You can perform operations on the node structure within this handler.

onOptionChanged

A handler for the optionChanged event. Executed after an option of the widget is changed.

Type: function
Function parameters:
Information about the event.
Object structure:
component: Object
The widget instance.
name: String
A short name of the option whose value has been changed.
fullName: String
A full name of the option whose value has been changed; contains a full hierarchy of the option.
value: any
A new value for the option.
element: jQuery
The widget's container.
model: Object
The model data. Available only if you use Knockout.
Default Value: null

onRowClick

A handler for the rowClick event. Executed when a user clicks a row.

Type: function(e) |String
Function parameters:
Information about the event.
Object structure:
component: Object
The widget's instance.
element: jQuery
The widget's container.
model: Object
The model data. Available only if you use Knockout.
jQueryEvent: jQuery.Event
The original jQuery event.
data: Object
The row data.
key: any
The row 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
Values displayed in the row cells.
columns: Array
All column Configurations.
rowIndex: Number
The row's visible index.
rowType: String
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: jQuery
The row's container.
handled: Boolean
Indicates whether internal widget handlers have already handled the event.
Default Value: null

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

When using DevExtreme SPA Framework, you can navigate to a specific URL on a click. For this, assign this URL or its anchor part (#) directly to this option.

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

onRowCollapsed

A handler for the rowCollapsed event. Executed after a row is collapsed.

Type: function(e)
Function parameters:
Information about the event.
Object structure:
component: Object
The widget instance.
element: jQuery
The widget's container.
model: Object
The model data. Available only if you use Knockout.
key: any
The key of the row.
Default Value: null

onRowCollapsing

A handler for the rowCollapsing event. Executed before a row is collapsed.

Type: function(e)
Function parameters:
Information about the event.
Object structure:
component: Object
The widget instance.
element: jQuery
The widget's container.
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 handler parameter.

onRowExpanded

A handler for the rowExpanded event. Executed after a row is expanded.

Type: function(e)
Function parameters:
Information about the event.
Object structure:
component: Object
The widget instance
element: jQuery
The widget's container.
model: Object
The model data. Available only if you use Knockout.
key: any
The key of the row.
Default Value: null

onRowExpanding

A handler for the rowExpanding event. Executed before a row is expanded.

Type: function(e)
Function parameters:
Information about the event.
Object structure:
component: Object
The widget instance.
element: jQuery
The widget's container.
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 handler parameter.

onRowInserted

A handler for the rowInserted event. Executed after a new row has been inserted into the data source.

Type: function(e)
Function parameters:
Information about the event.
Object structure:
component: Object
The widget instance.
element: jQuery
The widget's container.
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.
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 handler will be executed for each row individually.

onRowInserting

A handler for the rowInserting event. Executed before a new row is inserted into the data source.

Type: function(e)
Function parameters:
Information about the event.
Object structure:
component: Object
The widget instance.
element: jQuery
The widget's container.
model: Object
The model data. Available only if you use Knockout.
data: Object
The data of the to-be-inserted row.
Allows you to cancel row insertion.
Default Value: null

To cancel row insertion, assign true to the cancel field of the handler parameter. To perform an asynchronous action before inserting a row, assign a jQuery.Promise to the cancel field. The row will be inserted once the Deferred object of this Promise is resolved.

NOTE
In batch editing mode, if several rows are to be inserted, this handler will be executed for each row individually.

onRowPrepared

A handler for the rowPrepared event. Executed after the widget creates a row.

Type: function(e)
Function parameters:
Information about the event.
Object structure:
component: Object
The widget's instance.
element: jQuery
The widget's container.
model: Object
The model data. Available only if you use Knockout.
data: Object
The row data. Available if the rowType is 'data', 'detail' or 'detailAdaptive'.
key: any
The row 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: any
Values displayed in the row cells.
columns: Array
Configurations of all columns.
rowIndex: Number
The row's visible index.
rowType: String
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: jQuery
The row's container.
Default Value: null

onRowRemoved

A handler for the rowRemoved event. Executed after a row has been removed from the data source.

Type: function(e)
Function parameters:
Information about the event.
Object structure:
component: Object
The widget instance.
element: jQuery
The widget's container.
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.
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 handler will be executed for each row individually.

onRowRemoving

A handler for the rowRemoving event. Executed before a row is removed from the data source.

Type: function(e)
Function parameters:
Information about the event.
Object structure:
component: Object
The widget instance.
element: jQuery
The widget's container.
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.
Allows you to cancel row removal.
Default Value: null

To cancel row removal, assign true to the cancel field of the handler parameter. To perform an asynchronous action before removing the row, assign a jQuery.Promise to the cancel field. The row will be removed once the Deferred object of this Promise is resolved.

NOTE
In batch editing mode, if several rows are to be removed, this handler will be executed for each row individually.

onRowUpdated

A handler for the rowUpdated event. Executed after a row has been updated in the data source.

Type: function(e)
Function parameters:
Information about the event.
Object structure:
component: Object
The widget instance.
element: jQuery
The widget's container.
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.
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 handler will be executed for each row individually.

onRowUpdating

A handler for the rowUpdating event. Executed before a row is updated in the data source.

Type: function(e)
Function parameters:
Information about the event.
Object structure:
component: Object
The widget instance.
element: jQuery
The widget's container.
model: Object
The model data. Available only if you use Knockout.
oldData: Object
The old data of the row.
newData: Object
The updated 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.
Allows you to cancel row updating.
Default Value: null

To cancel row updating, assign true to the cancel field of the handler parameter. To perform an asynchronous action before updating the row, assign a jQuery.Promise to the cancel field. The row will be updated once the Deferred object of this Promise is resolved.

NOTE
In batch editing mode, if several rows are to be updated, this handler will be executed for each row individually.

onRowValidating

A handler for the rowValidating event. Executed after cells in a row are validated against validation rules.

Type: function(e)
Function parameters:
Information about the event.
Object structure:
component: Object
The widget instance.
element: jQuery
The widget's container.
model: Object
The model data. Available only if you use Knockout.
brokenRules: Array
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 handler to interfere before a message on the broken validation rules is displayed. For instance, you can perform additional checks in this handler and change the validation result by changing the isValid field of the handler 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 handler will be executed for each row.

onSelectionChanged

A handler for the selectionChanged event. Executed after selecting a row or clearing its selection.

Type: function(e)
Function parameters:
Information about the event.
Object structure:
component: Object
The widget instance.
element: jQuery
The widget's container.
model: Object
The model data. Available only if you use Knockout.
currentSelectedRowKeys: Array
The keys of the rows that have been selected.
currentDeselectedRowKeys: Array
The keys of the rows whose selection has been cleared.
selectedRowKeys: Array
The keys of all selected rows.
selectedRowsData: Array
The data of all selected rows.
Does not include calculated values.
Default Value: null

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

Call the byKey(key) method to retrieve data.

onToolbarPreparing

A handler for the toolbarPreparing event. Executed before the toolbar is created.

Type: function(e)
Function parameters:
Information about the event.
Object structure:
component: Object
The widget instance.
element: jQuery
The widget's container.
model: Object
The model data. Available only if you use Knockout.
toolbarOptions: Object
Default Value: null

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

JavaScript
$(function() {
    $("#treeListContainer").dxTreeList({
        // ...
        onToolbarPreparing: function (e) {
            var toolbarItems = e.toolbarOptions.items;
            // Modifies an existing item
            $.each(toolbarItems, 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'
            });
        }
    });
});

parentIdExpr

Specifies which data field provides parent keys.

Type: String| function
Default Value: 'parentId'
See Also

remoteOperations

Specifies what operations are performed on the server.

Type: String|Object
Default Value: 'auto'

Data for the TreeList can either be stored on the client or come from the server. As a rule, manipulating data on the server enhances the TreeList performance. However, the server might be falling short of implementing certain operations. In this case, they can be performed on the client.

Data operations can be categorized into basic operations (filtering, sorting) and advanced operations (grouping). The following table shows where data operations are performed by default.

Basic operations Advanced operations
CustomStore client client
ODataStore server client (always)
NOTE
You cannot perform data operations on the server with an ArrayStore, a LocalStore or an array of objects.

To control individual operations, assign a Boolean value to a corresponding field of the remoteOperations object. Note that making data operations remote makes sense only if data has a plain structure.

NOTE
If actual data is stored on the server, making data operations local does not guarantee that no queries for data will be sent to the server while these operations are being performed. It only guarantees that calculations will be performed on the client.

Note that when the operations are performed remotely, the TreeList does not support:

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. However, 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
});

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.

See Also

selectedRowKeys

Specifies the keys of rows that must be selected initially.

Type: Array

To access a row by its key, you should specify the field that provides keys. For this, use the key option of the Store that underlies the dataSource. If no key was specified, the whole data object is considered the key. However, we recommend specifying the key option to prevent selection from being duplicated.

See Also

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
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
Default for ios: true

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.

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 width of the widget.

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

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

  • Number
    The width of the widget 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