- Qt 6.9
- Qt Quick
- QML Types
- TreeView
- Qt 6.9.3 Reference Documentation

# TreeView QML Type

Provides a tree view to display data from a QAbstractItemModel. More...

Import Statement: | `import QtQuick`
Since: | Qt 6.3
Inherits: | TableView

- List of all members, including inherited members

## Properties

- rootIndex : QModelIndex `(since 6.6)`

## Signals

- collapsed(row, recursively)
- expanded(row, depth)

## Methods

- collapse(row)
- collapseRecursively(row) `(since 6.4)`
- int depth(row)
- expand(row)
- expandRecursively(row, depth) `(since 6.4)`
- expandToIndex(QModelIndex index) `(since 6.4)`
- bool isExpanded(row)
- toggleExpanded(row)

## Detailed Description

A TreeView has a model that defines the data to be displayed, and a delegate that defines how the data should be displayed.

TreeView inherits TableView. This means that, despite the model has a parent-child tree structure, TreeView is internally using a proxy model that converts that structure into a flat table model that can be rendered by TableView. Each node in the tree ends up occupying one row in the table, where the first column renders the tree itself. By indenting each delegate item in that column according to its parent-child depth in the model, it will end up looking like a tree, even if it's technically still just a flat list of items.

### Declare a TreeView

TreeView is a data bound control, so it cannot show anything without a data model. You cannot declare tree nodes in QML.

When you declare a TreeView, you need to specify:

- A data model. TreeView can work with data models that derive from QAbstractItemModel.
- A delegate. A delegate is a template that specifies how the tree nodes are displayed in the UI.

     TreeView {
         // The model needs to be a QAbstractItemModel
         model: myTreeModel
         // You can set a custom delegate or use a built-in TreeViewDelegate
         delegate: TreeViewDelegate {}
     }

### Creating a data model

A TreeView only accepts a model that inherits QAbstractItemModel.

For information on how to create and use a custom tree model, see the example: Qt Quick Controls - Table of Contents.

### Customize tree nodes

For better flexibility, TreeView itself doesn't position the delegate items into a tree structure. This burden is placed on the delegate. Qt Quick Controls offers a ready-made TreeViewDelegate that can be used for this, which has the advantage that it works out-of-the-box and renders a tree which follows the style of the platform where the application runs.

Even though TreeViewDelegate is customizable, there might be situations where you want to render the tree in a different way, or ensure that the delegate ends up as minimal as possible, perhaps for performance reasons. Creating your own delegate from scratch is easy, since TreeView offers a set of properties that can be used to position and render each node in the tree correctly.

An example of a custom delegate with an animating indicator is shown below:

     import QtQuick
     import QtQuick.Controls

     ApplicationWindow {
         width: 800
         height: 600
         visible: true

         TreeView {
             id: treeView
             anchors.fill: parent
             anchors.margins: 10
             clip: true

             selectionModel: ItemSelectionModel {}

             // The model needs to be a QAbstractItemModel
             // model: yourTreeModel

             delegate: Item {
                 implicitWidth: padding + label.x + label.implicitWidth + padding
                 implicitHeight: label.implicitHeight * 1.5

                 readonly property real indentation: 20
                 readonly property real padding: 5

                 // Assigned to by TreeView:
                 required property TreeView treeView
                 required property bool isTreeNode
                 required property bool expanded
                 required property bool hasChildren
                 required property int depth
                 required property int row
                 required property int column
                 required property bool current

                 // Rotate indicator when expanded by the user
                 // (requires TreeView to have a selectionModel)
                 property Animation indicatorAnimation: NumberAnimation {
                     target: indicator
                     property: "rotation"
                     from: expanded ? 0 : 90
                     to: expanded ? 90 : 0
                     duration: 100
                     easing.type: Easing.OutQuart
                 }
                 TableView.onPooled: indicatorAnimation.complete()
                 TableView.onReused: if (current) indicatorAnimation.start()
                 onExpandedChanged: indicator.rotation = expanded ? 90 : 0

                 Rectangle {
                     id: background
                     anchors.fill: parent
                     color: row === treeView.currentRow ? palette.highlight : "black"
                     opacity: (treeView.alternatingRows && row % 2 !== 0) ? 0.3 : 0.1
                 }

                 Label {
                     id: indicator
                     x: padding + (depth * indentation)
                     anchors.verticalCenter: parent.verticalCenter
                     visible: isTreeNode && hasChildren
                     text: "▶"

                     TapHandler {
                         onSingleTapped: {
                             let index = treeView.index(row, column)
                             treeView.selectionModel.setCurrentIndex(index, ItemSelectionModel.NoUpdate)
                             treeView.toggleExpanded(row)
                         }
                     }
                 }

                 Label {
                     id: label
                     x: padding + (isTreeNode ? (depth + 1) * indentation : 0)
                     anchors.verticalCenter: parent.verticalCenter
                     width: parent.width - padding - x
                     clip: true
                     text: model.display
                 }
             }
         }
     }

The properties that are marked as `required` will be filled in by TreeView, and are similar to attached properties. By marking them as required, the delegate indirectly informs TreeView that it should take responsibility for assigning them values. The following required properties can be added to a delegate:

- `required property TreeView treeView` - Points to the TreeView that contains the delegate item.
- `required property bool isTreeNode` - Is `true` if the delegate item represents a node in the tree. Only one column in the view will be used to draw the tree, and therefore, only delegate items in that column will have this property set to `true`. A node in the tree should typically be indented according to its `depth`, and show an indicator if `hasChildren` is `true`. Delegate items in other columns will have this property set to `false`, and will show data from the remaining columns in the model (and typically not be indented).
- `required property bool expanded` - Is `true` if the model item drawn by the delegate is expanded in the view.
- `required property bool hasChildren` - Is `true` if the model item drawn by the delegate has children in the model.
- `required property int depth` - Contains the depth of the model item drawn by the delegate. The depth of a model item is the same as the number of ancestors it has in the model.

See also Required Properties.

### End-user interaction

By default, TreeView toggles the expanded state of a row when you double tap on it. Since this is in conflict with double tapping to edit a cell, TreeView sets editTriggers to `TableView.EditKeyPressed` by default (which is different from TableView, which uses `TableView.EditKeyPressed | TableView.DoubleTapped`. If you change editTriggers to also contain `TableView.DoubleTapped`, toggling the expanded state with a double tap will be disabled.

## Property Documentation

rootIndex : QModelIndex `[since 6.6]`

This property holds the model index of the root item in the tree. By default, this is the same as the root index in the model, but you can set it to be a child index instead, to show only a branch of the tree. Set it to `undefined` to show the whole model.

This property was introduced in Qt 6.6.

## Signal Documentation

collapsed(row, recursively)

This signal is emitted when a row is collapsed in the view. row will be equal to the argument given to the call that caused the collapse to happen (collapse() or collapseRecursively()). If the row was collapsed recursively, recursively will be `true`.

Note: when a row is collapsed recursively, the collapsed signal will only be emitted for that one row, and not for its descendants.

Note: The corresponding handler is `onCollapsed`.

See also expanded(), expand(), collapse(), and toggleExpanded().

expanded(row, depth)

This signal is emitted when a row is expanded in the view. row and depth will be equal to the arguments given to the call that caused the expansion to happen (expand() or expandRecursively()). In case of expand(), depth will always be `1`. In case of expandToIndex(), depth will be the depth of the target index.

Note: when a row is expanded recursively, the expanded signal will only be emitted for that one row, and not for its descendants.

Note: The corresponding handler is `onExpanded`.

See also collapsed(), expand(), collapse(), and toggleExpanded().

## Method Documentation

collapse(row)

Collapses the tree node at the given row in the view.

row should be the row in the view (table row), and not a row in the model.

Note: this function will not affect the model, only the visual representation in the view.

See also expand() and isExpanded().

`[since 6.4]` collapseRecursively(row = -1)

Collapses the tree node at the given row in the view recursively down to all leaves.

For a model has more than one root, you can also call this function with row equal to `-1`. This will collapse all roots. Hence, calling collapseRecursively(-1), or simply collapseRecursively(), will collapse all nodes in the model.

row should be the row in the view (table row), and not a row in the model.

Note: this function will not affect the model, only the visual representation in the view.

This method was introduced in Qt 6.4.

See also expandRecursively(), expand(), collapse(), isExpanded(), and depth().

int depth(row)

Returns the depth (the number of parents up to the root) of the given row.

row should be the row in the view (table row), and not a row in the model. If row is not between `0` and rows, the return value will be `-1`.

See also modelIndex().

expand(row)

Expands the tree node at the given row in the view.

row should be the row in the view (table row), and not a row in the model.

Note: this function will not affect the model, only the visual representation in the view.

See also collapse(), isExpanded(), and expandRecursively().

`[since 6.4]` expandRecursively(row = -1, depth = -1)

Expands the tree node at the given row in the view recursively down to depth. depth should be relative to the depth of row. If depth is `-1`, the tree will be expanded all the way down to all leaves.

For a model that has more than one root, you can also call this function with row equal to `-1`. This will expand all roots. Hence, calling expandRecursively(-1, -1), or simply expandRecursively(), will expand all nodes in the model.

row should be the row in the view (table row), and not a row in the model.

Note: This function will not try to fetch more data.

Note: This function will not affect the model, only the visual representation in the view.

Warning: If the model contains a large number of items, this function will take some time to execute.

This method was introduced in Qt 6.4.

See also collapseRecursively(), expand(), collapse(), isExpanded(), and depth().

`[since 6.4]` expandToIndex(QModelIndex index)

Expands the tree from the given model index, and recursively all the way up to the root. The result will be that the delegate item that represents index becomes visible in the view (unless it ends up outside the viewport). To ensure that the row ends up visible in the viewport, you can do:

     expandToIndex(index)
     forceLayout()
     positionViewAtRow(rowAtIndex(index), Qt.AlignVCenter)

This method was introduced in Qt 6.4.

See also expand() and expandRecursively().

bool isExpanded(row)

Returns if the given row in the view is shown as expanded.

row should be the row in the view (table row), and not a row in the model. If row is not between `0` and rows, the return value will be `false`.

toggleExpanded(row)

Toggles if the tree node at the given row should be expanded. This is a convenience for doing:

     if (isExpanded(row))
         collapse(row)
     else
         expand(row)

row should be the row in the view (table row), and not a row in the model.