Frappe Tree API Guide (v15)

What is the Tree API in Frappe?

The Tree API in Frappe provides a consistent interface to build and render hierarchical datasets in the Tree View inside Desk. It is based on a Parent-Child DocType structure, enabling linked objects such as Chart of Accounts, Departments, and Item Groups.
Tree Views allow users to expand nodes, manage hierarchy, and manipulate relational data without a custom UI.

When to use a Tree View?

Use a Tree View when data naturally forms a hierarchy:

• Department structure
• Chart of Accounts
• Item Groups
• Cost Centers
• Organizational Trees
• Territory Hierarchies
• BOM Structure
• Project Task Trees

Tree Views eliminate the need for custom UI code to represent nested relational models.

How Tree API works in Frappe

A Tree View is enabled by:

1. A DocType with is_tree = 1
2. A parent field pointing to the same DocType
3. A lft and rgt index (nested set model)
4. A Tree List endpoint exposed by Desk
5. A Tree UI renderer

Frappe uses the Nested Set model to build trees efficiently.

Relevant fields:

Defining a Tree DocType

Step 1 — Enable Tree View in DocType

Open the DocType and enable:

Is Tree: Checked

This tells Frappe to treat the DocType using the nested set model instead of a flat list.

Step 2 — Parent Field Naming Pattern

For a DocType called Department, the parent field must be:

parent_department

Pattern:

parent_<doctype name in lowercase>

This is a required convention for the Tree Builder.

Step 3 — Add Fields Required

Frappe will automatically create:

• lft: left nested index
• rgt: right nested index

Used to build the hierarchy.

Accessing Tree Data via API

The Tree API is accessed using Frappe’s standard API routing:

Fetch Tree Nodes

frappe.call({
method: 'frappe.desk.treeview.get_children',
args: {
doctype: 'Department',
parent: 'All Departments'
},
callback: function(r) {
console.log(r.message);
}
});

Parameters:

• doctype: the Tree DocType
• parent: node to expand

Response:

A list of child nodes containing:

[
{
"value": "Finance",
"expandable": 1,
"node_type": "Department",
"leaf": 0
}
]

Add Child Node

frappe.call({
method: 'frappe.desk.treeview.add_node',
args: {
doctype: 'Department',
parent: 'All Departments',
name: 'HR'
}
});

Rename Tree Node

frappe.call({
method: 'frappe.desk.treeview.rename_node',
args: {
doctype: 'Department',
old: 'HR',
new: 'Human Resources'
}
});

Delete Tree Node

frappe.call({
method: 'frappe.desk.treeview.delete_node',
args: {
doctype: 'Department',
name: 'Human Resources'
}
});

Server-side Tree API (Python)

Frappe provides Python utilities for Tree data.
Import Nested Set functions from frappe.utils.nestedset:

from frappe.utils.nestedset import rebuild_tree

Rebuilding Tree Index

rebuild_tree("Department", "parent_department")

Use this to regenerate lft and rgt when bulk-inserting records.

How to Enable Tree UI

Tree support is automatically active when:

• is_tree = 1
• Parent field is defined
• DocType is loaded in Desk

The view appears under:

/app/doctype-name/tree

Example:

/app/department/tree

Tree UI Configuration

Row Fields Display

Use treeview_settings to configure:
hooks.py:
treeviews = ["Department", "Territory"]

Optional UI configuration:

frappe.treeview_settings["Department"] = {
get_tree_nodes: "frappe.desk.treeview.get_children",
add_tree_node: "frappe.desk.treeview.add_node",
rename_node: "frappe.desk.treeview.rename_node",
delete_node: "frappe.desk.treeview.delete_node"
}

Best Practices

• Always follow parent naming convention
• Use Tree View only when hierarchy exists
• Avoid overloading Tree with heavy children lists
• Control permissions with server-side checks
• Use rebuild_tree() after bulk imports
• Implement is_group indicator for folders
• Avoid nesting deeper than required
• Store business logic in Python

Technical References (v15 Verified)

GitHub Tree code:
https://github.com/frappe/frappe/tree/version-15/frappe/desk/treeview

Tree API controller:

frappe/desk/treeview.py

frappe/utils/nestedset.py

Docs Reference:
https://docs.frappe.io/framework/user/en/api/tree