A newer version of this page is available. Switch to the current version.


  • 7 minutes to read

Tree List nodes are data rows organized into a tree-like hierarchy.

Tree List 2018 - Nodes


API Demos

Add New Nodes

Nodes (the TreeListNode class objects) are generated automatically if a Tree List has a data source. To add nodes in Unbound Mode, invoke the Tree List Designer dialog and switch to its "Nodes" tab .

Tree List 2018 - Add Nodes

Refer to the Unbound Mode article for information on how to add custom nodes in code.

Access Nodes

The TreeList.Nodes property allows you to access nodes from the control's root level.

//get a second node by indexer
TreeListNode node = treeList1.Nodes[1];
//get all nodes whose caption has "R&D" in it
var nodes = treeList1.Nodes.Where(n => n.GetDisplayText("Department").Contains("R&D"));

Every node has a TreeList.Nodes collection that stores child nodes. You can use the nodes iterator or the following API to retrieve nodes in these collections:

Node Icons

A node cell can contain an icon. This section describes various approaches that you can use to display an image in a cell.

Select and State Icons

Every node can have the select and state icons.




Select icon

Tree List 2018 - Select Images

The main node image. Use the TreeListNode.ImageIndex property to choose an icon from the TreeList.SelectImageList collection assigned to the Tree List.

The optional TreeListNode.SelectImageIndex property allows you to specify another icon for the same node. This image is shown when the node is focused (selected).

State icon

Tree List 2018 - State Images

State icons are shown next to select icons and indicate a node's state. These icons are stored in a separate TreeList.StateImageList collection. Use the TreeListNode.StateImageIndex property to choose a state image from this collection.

If the TreeListOptionsView.RowImagesShowMode property is set to InCell, icons are shown inside node cells.

Tree List 2018 - Icons inside cells

See Node Image for more information.

Conditional Formatting

This approach is recommended when you have a set of icons that visualize different values or value ranges. In the image below, icons that indicate the market share growth are displayed next to cell values.


Run the Conditional Formatting (MS Excel style) module in the XtraTreeList Main Demo for the complete example. Click Open Solution in the ribbon for source codes.

See Conditional Formatting for more information.

Combo Box with Images

This approach allows you to supply cell values with images or completely replace text entries with these images. The code below illustrates how to replace check boxes with icons in columns that contain boolean values.

using DevExpress.XtraEditors.Repository;

RepositoryItemImageComboBox repositoryItemDescriptionComboBox;
repositoryItemDescriptionComboBox = new RepositoryItemImageComboBox();
repositoryItemDescriptionComboBox.AutoHeight = false;
repositoryItemDescriptionComboBox.GlyphAlignment = DevExpress.Utils.HorzAlignment.Center;
repositoryItemDescriptionComboBox.SmallImages = svgImageCollection;
repositoryItemDescriptionComboBox.Items.Add("", true, 3);

descriptionColumn.ColumnEdit = repositoryItemDescriptionComboBox;

Run the Hierarchy Column module in the XtraTreeList Main Demo for the complete example. Click Open Solution in the ribbon for source codes.

Context Icons in Text Box

The RepositoryItemTextEdit.ContextImageOptions group provides access to properties that allow you to assign a raster or vector icon to a text box. You can display the same icon in all cells that utilize this repository item. To display another icon in individual cells, create another RepositoryItemTextEdit object and handle the TreeList.CustomNodeCellEdit event to assign this repository item to a cell. In the example below, a text box with a context image is assigned to the cell that contains "Arthur Miller".

using DevExpress.XtraEditors.Repository;

RepositoryItemTextEdit repositoryItemTextEdit2;
repositoryItemTextEdit2 = new RepositoryItemTextEdit();
repositoryItemTextEdit2.ContextImageOptions.SvgImage = svgImageCollection[0];

private void treeList1_CustomNodeCellEdit(object sender, GetCustomNodeCellEditEventArgs e) {
    TreeList treeList = sender as TreeList;
    if(e.Node.Id != TreeList.NewItemNodeId && e.Column == employeeColumn && treeList.GetRowCellValue(e.Node, e.Column).ToString() == "Arthur Miller") {
        e.RepositoryItem = repositoryItemTextEdit2;

Unbound Columns

If you need a column with images that is not associated with specific data source values, create an unbound column with a RepositoryItemPictureEdit object as an in-place editor. Handle the TreeList.CustomUnboundColumnData event to supply this column with images.

HTML Formatting

Use the TreeList.HtmlImages collection and the Image HTML tag to embed images into cells. Note that this approach makes a cell non-editable.

treeList1.HtmlImages = svgImageCollection1;
treeList1.RowHeight = 60;
TreeListColumn unbound = new TreeListColumn();
unbound.UnboundType = DevExpress.XtraTreeList.Data.UnboundColumnType.String;
unbound.FieldName = "unboundImageColumn";
unbound.Visible = true;
unbound.Caption = "Icon";
RepositoryItemHypertextLabel htLabel = new RepositoryItemHypertextLabel();
htLabel.HtmlImages = svgImageCollection1;
unbound.ColumnEdit = htLabel;
treeList1.CustomUnboundColumnData += TreeList1_CustomUnboundColumnData;

private void TreeList1_CustomUnboundColumnData(object sender, DevExpress.XtraTreeList.TreeListCustomColumnDataEventArgs e) {
    if (e.Column.Caption == "Icon") {
        //image from a collection
        e.Value = "<image=add_32x32.png>";
        //image from resources
        //e.Value = "<image=#_589812_200>";

Draw a Cell

The CustomDrawNodeCell event allows you to manually re-paint cells, and draw custom images and shapes. In this example, an image is drawn in the cell that contains "Arthur Miller".

private void treeList1_CustomDrawNodeCell(object sender, CustomDrawNodeCellEventArgs e) {
    TreeList treeList = sender as TreeList;
    if (e.Node.Id != TreeList.NewItemNodeId && e.Column == employeeColumn && treeList.GetRowCellValue(e.Node, e.Column).ToString() == "Arthur Miller") {
        e.Cache.DrawImage(imageCollection1.Images[0], e.Bounds.X + offsetX, e.Bounds.Y + offsetY);

Node Indents

A node indent is a distance between the control's border and the border of a first cell in this node. The TreeList.TreeLevelWidth property specifies this distance for root nodes.


Node Checking with Checkboxes and Radio Buttons

The TreeList's node checking feature allows you to enable check boxes or radio buttons for certain tree levels.


You can set or retrieve the nodes' check states using the API the TreeList control provides. In bound mode, it is possible to sync node check states with a field in the data source. See Node Checking - Checkboxes and Radio Buttons for more information.

Preview Sections

Preview sections are non-editable regions display large memo text or custom data. They are displayed under nodes' data cells across all columns.


See the Preview Sections article for more information.