JavaScript/jQuery TreeList API

The TreeList is a widget that represents data from a local or remote source in the form of a multi-column tree view. This widget offers such features as sorting, filtering, editing, selection, etc.

import TreeList from "devextreme/ui/tree_list"

DevExtreme widgets are integrated with many popular libraries and frameworks. See the Installation section (for JavaScript libraries) or the Prerequisites and Installation section (for ASP.NET MVC framework) to find details on setting up DevExtreme with a particular library or framework.

The following code shows how to create the TreeList widget using every supported library and framework. For more details on working with widgets in these libraries and frameworks, see the Widget Basics topic for jQuery, Angular, AngularJS, Knockout or ASP.NET MVC.

jQuery

JavaScript

HTML

$(function () {
    $("#treeList").dxTreeList({
        dataSource: [
            { key: "1", fullName: "John Heart", position: "CEO" }, 
            { key: "1_1", head: "1", fullName: "Samantha Bright", position: "COO" }, 
            { key: "2_1", head: "2", fullName: "Robert Reagan", position: "CMO" }, 
            { key: "2", fullName: "Greta Sims", position: "HR Manager" }
        ],
        keyExpr: "key",
        parentIdExpr: "head",
        columns: ['fullName', 'position']
    });
});

<div id="treeList"></div>

Angular

HTML

TypeScript

<dx-tree-list 
    [dataSource]="employees"
    keyExpr="key"
    parentIdExpr="head">
    <dxi-column dataField="fullName"></dxi-column>
    <dxi-column dataField="position"></dxi-column>
</dx-tree-list>

export class AppComponent {
    employees = [
        { key: "1", fullName: "John Heart", position: "CEO" }, 
        { key: "1_1", head: "1", fullName: "Samantha Bright", position: "COO" }, 
        { key: "2_1", head: "2", fullName: "Robert Reagan", position: "CMO" }, 
        { key: "2", fullName: "Greta Sims", position: "HR Manager" }
    ];
}

AngularJS

HTML

JavaScript

<div ng-controller="DemoController">
    <div dx-tree-list="{
        dataSource: employees,
        keyExpr: 'key',
        parentIdExpr: 'head',
        columns: ['fullName', 'position']
    }"></div>
</div>

angular.module('DemoApp', ['dx'])
    .controller("DemoController", function ($scope) {
        $scope.employees = [
            { key: "1", fullName: "John Heart", position: "CEO" }, 
            { key: "1_1", head: "1", fullName: "Samantha Bright", position: "COO" }, 
            { key: "2_1", head: "2", fullName: "Robert Reagan", position: "CMO" }, 
            { key: "2", fullName: "Greta Sims", position: "HR Manager" }
        ];
    });

Knockout

HTML

JavaScript

<div data-bind="dxTreeList: {
    dataSource: employees,
    keyExpr: 'key',
    parentIdExpr: 'head',
    columns: ['fullName', 'position']
}"></div>

var viewModel = {
    employees: [
        { key: "1", fullName: "John Heart", position: "CEO" }, 
        { key: "1_1", head: "1", fullName: "Samantha Bright", position: "COO" }, 
        { key: "2_1", head: "2", fullName: "Robert Reagan", position: "CMO" }, 
        { key: "2", fullName: "Greta Sims", position: "HR Manager" }
    ]
};
ko.applyBindings(viewModel);

ASP.NET MVC Controls

Razor C#

Razor VB

@(Html.DevExtreme().TreeList()
    .ID("treeList")
    .DataSource(new object[] {
        new { key = "1", fullName = "John Heart", position = "CEO" },
        new { key = "1_1", head = "1", fullName = "Samantha Bright", position = "COO" },
        new { key = "2_1", head = "2", fullName = "Robert Reagan", position = "CMO" },
        new { key = "2", fullName = "Greta Sims", position = "HR Manager" }
    }, "key")
    .ParentIdExpr("head")
    .Columns(columns =>
    {
        columns.Add().DataField("fullName");
        columns.Add().DataField("position");
    })
)

@(Html.DevExtreme().TreeList() _
    .ID("treeList") _
    .DataSource({
        New With { .key = "1", .fullName = "John Heart", .position = "CEO" },
        New With { .key = "1_1", .head = "1", .fullName = "Samantha Bright", .position = "COO" },
        New With { .key = "2_1", .head = "2", .fullName = "Robert Reagan", .position = "CMO" },
        New With { .key = "2", .fullName = "Greta Sims", .position = "HR Manager" }
    }, "key") _
    .ParentIdExpr("head") _
    .Columns(Sub(columns)
        columns.Add().DataField("fullName")
        columns.Add().DataField("position")
    End Sub)
)

View Demo Watch Video

Configuration

An object defining configuration options for the TreeList widget.

Name	Description
accessKey	Specifies the shortcut key that sets focus on the widget.
activeStateEnabled	Specifies whether or not the widget changes its state when interacting with a user.
allowColumnReordering	Specifies whether a user can reorder columns.
allowColumnResizing	Specifies whether a user can resize columns.
autoExpandAll	Specifies whether all rows are expanded initially.
cacheEnabled	Specifies whether data should be cached.
cellHintEnabled	Enables a hint that appears when a user hovers the mouse pointer over a cell with truncated content.
columnAutoWidth	Specifies whether columns should adjust their widths to the content.
columnChooser	Configures the column chooser.
columnFixing	Configures column fixing.
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".
columnMinWidth	Specifies the minimum width of columns.
columnResizingMode	Specifies how the widget resizes columns. Applies only if allowColumnResizing is true.
columns	Configures columns.
customizeColumns	Customizes columns after they are created.
dataSource	Specifies the origin of data for the widget.
dataStructure	Notifies the widget of your data structure.
dateSerializationFormat	Specifies date-time values' serialization format. Use it only if you do not specify the dataSource at design time.
disabled	Specifies whether the widget responds to user interaction.
editing	Configures editing.
elementAttr	Specifies the attributes to be attached to the widget's root element.
errorRowEnabled	Indicates whether to show the error row.
expandedRowKeys	Specifies keys of the initially expanded rows.
expandNodesOnFiltering	Specifies whether nodes appear expanded or collapsed after filtering is applied.
filterRow	Configures the filter row.
focusStateEnabled	Specifies whether the widget can be focused using keyboard navigation.
hasItemsExpr	Specifies which data field defines whether the node has children.
headerFilter	Configures the header filter feature.
height	Specifies the widget's height.
hint	Specifies text for a hint that appears when a user pauses on the widget.
hoverStateEnabled	Specifies whether to highlight rows when a user moves the mouse pointer over them.
itemsExpr	Specifies which data field contains nested items. Set this option when your data has a hierarchical structure.
keyExpr	Specifies which data field provides keys for nodes.
loadPanel	Configures the load panel.
noDataText	Specifies text shown when the widget does not display any data.
onAdaptiveDetailRowPreparing	A handler for the adaptiveDetailRowPreparing event. Executed before an adaptive detail row is rendered.
onCellClick	A handler for the cellClick event. Executed after a user clicks a cell.
onCellHoverChanged	A handler for the cellHoverChanged event. Executed after the pointer enters or leaves a cell.
onCellPrepared	A handler for the cellPrepared event. Executed after the widget creates a cell.
onContentReady	A handler for the contentReady event. Executed when the widget's content is ready. This handler may be executed multiple times during the widget's lifetime depending on the number of times its content changes.
onContextMenuPreparing	A handler for the contextMenuPreparing event. Executed before a context menu is rendered.
onDataErrorOccurred	A handler for the dataErrorOccurred event. Executed when an error occurs in the data source.
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.
onEditingStart	A handler for the editingStart event. Executed before a cell or row switches to the editing state.
onEditorPrepared	A function that is executed after an editor is created.
onEditorPreparing	A function that is executed before an editor is created.
onInitialized	A handler for the initialized event. Executed only once, after the widget is initialized.
onInitNewRow	A handler for the initNewRow event. Executed before a new row is added to the widget.
onKeyDown	A handler for the keyDown event. Executed when the widget is in focus and a key has been pressed down.
onNodesInitialized	A handler for the nodesInitialized event. Executed after the loaded nodes are initialized.
onOptionChanged	A handler for the optionChanged event. Executed after an option of the widget is changed.
onRowClick	A handler for the rowClick event. Executed when a user clicks a row.
onRowCollapsed	A handler for the rowCollapsed event. Executed after a row is collapsed.
onRowCollapsing	A handler for the rowCollapsing event. Executed before a row is collapsed.
onRowExpanded	A handler for the rowExpanded event. Executed after a row is expanded.
onRowExpanding	A handler for the rowExpanding event. Executed before a row is expanded.
onRowInserted	A handler for the rowInserted event. Executed after a new row has been inserted into the data source.
onRowInserting	A handler for the rowInserting event. Executed before a new row is inserted into the data source.
onRowPrepared	A handler for the rowPrepared event. Executed after the widget creates a row.
onRowRemoved	A handler for the rowRemoved event. Executed after a row has been removed from the data source.
onRowRemoving	A handler for the rowRemoving event. Executed before a row is removed from the data source.
onRowUpdated	A handler for the rowUpdated event. Executed after a row has been updated in the data source.
onRowUpdating	A handler for the rowUpdating event. Executed before a row is updated in the data source.
onRowValidating	A handler for the rowValidating event. Executed after cells in a row are validated against validation rules.
onSelectionChanged	A handler for the selectionChanged event. Executed after selecting a row or clearing its selection.
onToolbarPreparing	A handler for the toolbarPreparing event. Executed before the toolbar is created.
parentIdExpr	Specifies which data field provides parent keys.
remoteOperations	Specifies what operations are performed on the server.
rootValue	Specifies the root node's identifier. Applies if dataStructure is 'plain'.
rowAlternationEnabled	Specifies whether rows should be shaded differently.
rtlEnabled	Switches the widget to a right-to-left representation.
scrolling	Configures scrolling.
searchPanel	Configures the search panel.
selectedRowKeys	Allows you to select rows or learn which rows are selected.
selection	Configures runtime selection.
showBorders	Specifies whether the outer borders of the widget are visible.
showColumnHeaders	Specifies whether column headers are visible.
showColumnLines	Specifies whether vertical lines that separate one column from another are visible.
showRowLines	Specifies whether horizontal lines that separate one row from another are visible.
sorting	Configures runtime sorting.
tabIndex	Specifies the number of the element when the Tab key is used for navigating.
twoWayBindingEnabled	Specifies whether to enable two-way data binding.
visible	Specifies whether the widget is visible.
width	Specifies the widget's width.
wordWrapEnabled	Specifies whether text that does not fit into a column should be wrapped.

Methods

This section describes methods that you can use to manipulate the TreeList widget in code.

Name	Description
addColumn(columnOptions)	Adds a new column.
addRow()	Adds an empty data row to the highest hierarchical level.
addRow(parentId)	Adds an empty data row to a specified parent row.
beginCustomLoading(messageText)	Shows the load panel.
beginUpdate()	Prevents the widget from refreshing until the endUpdate() method is called.
byKey(key)	Gets a data object with a specific key.
cancelEditData()	Discards changes that a user made to data.
cellValue(rowIndex, dataField)	Gets the value of a cell with a specific row index and a data field.
cellValue(rowIndex, dataField, value)	Sets a new value to a cell with a specific row index and a data field.
cellValue(rowIndex, visibleColumnIndex)	Gets the value of a cell with specific row and column indexes.
cellValue(rowIndex, visibleColumnIndex, value)	Sets a new value to a cell with specific row and column indexes.
clearFilter()	Clears all filters applied to widget rows.
clearFilter(filterName)	Clears all row filters of a specific type.
clearSelection()	Clears selection of all rows on all pages.
clearSorting()	Clears sorting settings of all columns at once.
closeEditCell()	Switches the cell being edited back to the normal state. Takes effect only if editing.mode is batch and showEditorAlways is false.
collapseAdaptiveDetailRow()	Collapses the currently expanded adaptive detail row (if there is one).
collapseRow(key)	Collapses a row with a specific key.
columnCount()	Gets the data column count. Includes visible and hidden columns, excludes command columns.
columnOption(id)	Gets all options of a column with a specific identifier.
columnOption(id, optionName)	Gets the value of a single column option.
columnOption(id, optionName, optionValue)	Updates the value of a single column option.
columnOption(id, options)	Updates the values of several column options.
defaultOptions(rule)	Specifies the device-dependent default configuration options for this component.
deleteColumn(id)	Removes a column.
deleteRow(rowIndex)	Removes a row with a specific index.
deselectAll()	Clears the selection of all rows on all pages or the currently rendered page only.
deselectRows(keys)	Cancels the selection of rows with specific keys.
dispose()	Disposes of all the resources allocated to the TreeList instance.
editCell(rowIndex, dataField)	Switches a cell with a specific row index and a data field to the editing state. Takes effect only if the editing mode is 'batch' or 'cell'.
editCell(rowIndex, visibleColumnIndex)	Switches a cell with specific row and column indexes to the editing state. Takes effect only if the editing mode is 'batch' or 'cell'.
editRow(rowIndex)	Switches a row with a specific index to the editing state. Takes effect only if the editing mode is 'row', 'popup' or 'form'.
element()	Gets the root widget element.
endCustomLoading()	Hides the load panel.
endUpdate()	Refreshes the widget after a call of the beginUpdate() method.
expandAdaptiveDetailRow(key)	Expands an adaptive detail row.
expandRow(key)	Expands a row with a specific key.
filter()	Gets a filter expression applied to the widget's data source using the filter(filterExpr) method.
filter(filterExpr)	Applies a filter to the widget's data source.
focus()	Sets focus on the widget.
focus(element)	Sets focus on a specific cell.
forEachNode(callback)	Performs a pre-order tree traversal, executing a function on each visited node. Starts traversing from the top level nodes.
forEachNode(nodes, callback)	Performs a pre-order tree traversal, executing a function on each visited node. Starts traversing from the specified nodes.
getCellElement(rowIndex, dataField)	Gets a cell with a specific row index and a data field.
getCellElement(rowIndex, visibleColumnIndex)	Gets a cell with specific row and column indexes.
getCombinedFilter()	Gets the total filter that combines all the filters applied.
getCombinedFilter(returnDataField)	Gets the total filter that combines all the filters applied.
getDataSource()	Gets the DataSource instance.
getInstance(element)	Gets the instance of a widget found using its DOM node.
getKeyByRowIndex(rowIndex)	Gets the key of a row with a specific index.
getNodeByKey(key)	Gets a node with a specific key.
getRootNode()	Gets the root node.
getRowElement(rowIndex)	Gets the container of a row with a specific index.
getRowIndexByKey(key)	Gets the index of a row with a specific key.
getScrollable()	Gets the instance of the widget's scrollable part.
getSelectedRowKeys()	Gets the currently selected rows' keys.
getSelectedRowKeys(leavesOnly)	Gets the currently selected row keys.
getSelectedRowsData()	Gets data objects of currently selected rows.
getVisibleColumns()	Gets all visible columns.
getVisibleColumns(headerLevel)	Gets all visible columns at a specific hierarchical level of column headers. Use it to access banded columns.
getVisibleRows()	Gets currently rendered rows.
hasEditData()	Checks whether the widget has unsaved changes.
hideColumnChooser()	Hides the column chooser.
instance()	Gets the widget's instance. Use it to access other methods of the widget.
isAdaptiveDetailRowExpanded(key)	Checks whether an adaptive detail row is expanded or collapsed.
isRowExpanded(key)	Checks whether a row is expanded or collapsed.
isRowSelected(key)	Checks whether a row with a specific key is selected.
keyOf(obj)	Gets a data object's key.
loadDescendants()	Loads all root node descendants (all data items). Takes effect only if data has the plain structure and remoteOperations \| filtering is true.
loadDescendants(keys)	Loads a specific node's descendants. Takes effect only if data has the plain structure and remoteOperations \| filtering is true.
loadDescendants(keys, childrenOnly)	Loads all or only direct descendants of specific nodes. Takes effect only if data has the plain structure and remoteOperations \| filtering is true.
off(eventName)	Detaches all event handlers from a single event.
off(eventName, eventHandler)	Detaches a particular event handler from a single event.
on(eventName, eventHandler)	Subscribes to an event.
on(events)	Subscribes to events.
option()	Gets all widget options.
option(optionName)	Gets the value of a single option.
option(optionName, optionValue)	Updates the value of a single option.
option(options)	Updates the values of several options.
refresh()	Reloads data in the widget.
repaint()	Repaints the widget. Call it if you made modifications that changed the widget's state to invalid.
repaintRows(rowIndexes)	Repaints specific rows.
saveEditData()	Saves changes that a user made to data.
searchByText(text)	Seeks a search string in the columns whose allowSearch option is true.
selectAll()	Selects all rows.
selectRows(keys, preserve)	Selects rows with specific keys.
selectRowsByIndexes(indexes)	Selects rows with specific indexes.
showColumnChooser()	Shows the column chooser.
undeleteRow(rowIndex)	Recovers a row deleted in batch editing mode.
updateDimensions()	Updates the widget's content after resizing.

Events

This section describes events raised by this widget.

Name	Description
adaptiveDetailRowPreparing	Raised before an adaptive detail row is rendered.
cellClick	Raised when a user clicks a cell.
cellHoverChanged	Raised when the pointer enters or leaves a cell.
cellPrepared	Raised after a cell is created.
contentReady	Raised when the widget's content is ready.
contextMenuPreparing	Raised before a context menu is rendered.
dataErrorOccurred	Raised when an error occurs in the data source.
disposing	Raised when the widget is removed from the DOM using the remove(), empty(), or html() jQuery methods only.
editingStart	Raised before a cell or row switches to the editing state.
editorPrepared	Raised after an editor is created.
editorPreparing	Raised before an editor is created.
initialized	Raised only once, after the widget is initialized.
initNewRow	Raised before a new row is added to the widget.
keyDown	Raised when the widget is in focus and a key has been pressed down.
nodesInitialized	Raised after all widget nodes are initialized.
optionChanged	Raised after a widget option is changed.
rowClick	Raised when a user clicks a row.
rowCollapsed	Raised after a row is collapsed.
rowCollapsing	Raised before a row is collapsed.
rowExpanded	Raised after a row is expanded.
rowExpanding	Raised before a row is expanded.
rowInserted	Raised after a new row has been inserted into the data source.
rowInserting	Raised before a new row is inserted into the data source.
rowPrepared	Raised after a row is created.
rowRemoved	Raised after a row has been removed from the data source.
rowRemoving	Raised before a row is removed from the data source.
rowUpdated	Raised after a row has been updated in the data source.
rowUpdating	Raised before a row is updated in the data source.
rowValidating	Raised after cells in a row are validated against validation rules.
selectionChanged	Raised after selecting a row or clearing its selection.
toolbarPreparing	Raised before the toolbar is created.

Node

A TreeList node's structure.

Type:

Object

You can access nodes using the getRootNode() method and within some event handlers, for example, onNodesInitialized.

Row

The TreeList row object's structure.

Type:

Object

A row is a visual representation of a node. Row objects can be accessed using the getVisibleRows() method and within some event handlers, for example, onCellClick or onRowClick.

JavaScript/jQuery TreeList API

jQuery

Angular

AngularJS

Knockout

ASP.NET MVC Controls

See Also

Configuration

Methods

Events

See Also

Node

Row