Skip to content

tree

A control that allows for selecting items from a hierarchical view of items.

Each item is represented by a string, an image, or both.

The tree can let the user select multiple items.

A filtering feature is available to display only a subset of the items.

You can use an arbitrary type for all the items (see the example).

Properties

Name Type Default Description
value(★) any
dynamic

Bound to the selection value.

expanded bool|str[]
dynamic
True

If Boolean and False, only one node can be expanded at one given level. Otherwise this should be set to an array of the node identifiers that need to be expanded.

multiple bool False

If True, the user can select multiple items by holding the Ctrl key while clicking on items.

select_leafs_only bool False

If True, the user can only select leaf nodes.

row_height str

The height, in CSS units, of each row.

filter bool False

If True, this control is combined with a filter input area.

width str|int "360px"

The width, in CSS units, of this element.

height str|int

The height, in CSS units, of this element.

dropdown bool False

If True, the list of items is shown in a dropdown menu.

You cannot use the filter in that situation.

label str None

The label associated with the selector when in dropdown mode.

mode str

Define the way the selector is displayed:

  • "radio": list of radio buttons
  • "check": list of check buttons
  • any other value: selector as usual.

lov dict[str, any]

The list of values. See the section on List of Values for details.

adapter Function `lambda x: str(x)`

The function that transforms an element of lov into a tuple(id:str, label:str|Icon).

type str Type of first lov element

Must be specified if lov contains a non-specific type of data (ex: dict).
value must be of that type, lov must be an iterable on this type, and the adapter function will receive an object of this type.

value_by_id bool False

If False, the selection value (in value) is the selected element in lov. If set to True, then value is set to the id of the selected element in lov.

on_change Callback

The name of a function that is triggered when the value is updated.
The parameters of that function are all optional:

  • state (State): the state instance.
  • var_name (str): the variable name.
  • value (any): the new value.

propagate bool App config

Allows the control's main value to be automatically propagated.
The default value is defined at the application configuration level.
If True, any change to the control's value is immediately reflected in the bound application variable.

active bool
dynamic
True

Indicates if this component is active.
An inactive component allows no user interaction.

id str

The identifier that will be assigned to the rendered HTML component.

properties dict[str, any]

Bound to a dictionary that contains additional properties for this element.

class_name str
dynamic

The list of CSS class names that will be associated with the generated HTML Element.
These class names will be added to the default taipy-<element_type>.

hover_text str
dynamic

The information that is displayed when the user hovers over this element.

(★)value is the default property for this visual element.

Styling

All the tree controls are generated with the "taipy-tree" CSS class. You can use this class name to select the tree controls on your page and apply style.

Usage

Display a list of string

You can create a tree on a series of strings:

Definition

<|{value}|tree|lov=Item 1;Item 2;Item 3|>
<taipy:tree lov="Item 1;Item 2;Item 3">{value}</taipy:tree>
import taipy.gui.builder as tgb
...
tgb.tree("{value}", lov="Item 1;Item 2;Item 3")

Display with filter and multiple selection

You can add a filter input field that lets you display only strings that match the filter value.

The following tree definition will create a tree control that shows the filter selection (setting the filter property to True) and allows users to select multiple items (setting the multiple property to True):

Definition

<|{value}|tree|lov=Item 1;Item 2;Item 3|filter|multiple|>
<taipy:tree lov="Item 1;Item 2;Item 3" filter multiple>{value}</taipy:tree>
import taipy.gui.builder as tgb
...
tgb.tree("{value}", lov="Item 1;Item 2;Item 3", filter=True, multiple=True)

Display a list of tuples

The lov property value can be defined so that the tree displays labels and icons while reflecting the selection by identifiers:

Definition

<|{sel}|tree|lov={[("id1", "Label 1", [("id1.1", "Label 1.1"), ("id1.2", "Label 1.2")]), ("id2", Icon("/images/icon.png", "Label 2")), ("id3", "Label 3", [("id3.1", "Label 3.1"), ("id3.2", "Label 3.2")])]}|>
<taipy:tree lov="{[('id1', 'Label 1', [('id1.1', 'Label 1.1'), ('id1.2', 'Label 1.2')]), ('id2', Icon('/images/icon.png', 'Label 2')), ('id3', 'Label 3', [('id3.1', 'Label 3.1'), ('id3.2', 'Label 3.2')])]}">
{sel}</taipy:tree>
import taipy.gui.builder as tgb
...
tgb.tree("{sel}", lov="{[('id1', 'Label 1', [('id1.1', 'Label 1.1'), ('id1.2', 'Label 1.2')]), ('id2', Icon('/images/icon.png', 'Label 2')), ('id3', 'Label 3', [('id3.1', 'Label 3.1'), ('id3.2', 'Label 3.2')])]}")

Manage expanded nodes

The property expanded must be used to control the expanded/collapse state of the nodes. By default, the user can expand or collapse nodes.
If expanded is set to False, there can be only one expanded node at any given level of the tree: if a node is expanded at a certain level and the user clicks on another node at the same level, the first node will be automatically collapsed.

The expanded property can also hold a list of node identifiers that are expanded.

Definition

<|{value}|tree|lov=Item 1;Item 2;Item 3|not expanded|>

<|{value}|tree|lov=Item 1;Item 2;Item 3|expanded=Item 2|>
<taipy:tree value="{value}" lov="Item 1;Item 2;Item 3" expanded="False" />

<taipy:tree value="{value}" lov="Item 1;Item 2;Item 3" expanded="Item 2" />
import taipy.gui.builder as tgb
...
tgb.tree("value", lov="Item 1;Item 2;Item 3", expanded=False)
tgb.tree("value", lov="Item 1;Item 2;Item 3", expanded="Item 2")

Display a tree of dictionary entries

The tree control has a predefined adapter that can display the definition of a dictionary structure set to the lov property as long as each dictionary entry has an id and a label key, as well as a children key that would hold, in a list, the children of a given entry. Each child has the same constraints: the id, label, and children keys must be present.
An entry with no children needs to set an empty list as the value of its
children* key.

Here is an example. Assuming your Python code has created a list of dictionaries:

users = [
    {"id": "231", "label": "Johanna", "year": 1987, "children": [{"id": "231.1", "label": "Johanna's son", "year": 2006}]},
    {"id": "125", "label": "John",    "year": 1979, "children": []},
    {"id": "4",   "label": "Peter",   "year": 1968, "children": []},
    {"id": "31",  "label": "Mary",    "year": 1974, "children": []}
    ]

user_sel = users[2]

The definition of a tree control that can represent this data is as simple as:

Definition

<|{user_sel}|tree|lov={users}|>
<taipy:tree lov="{users}">{user_sel}</taipy:tree>
import taipy.gui.builder as tgb
...
tgb.tree("{user_sel}", lov="{users}")

Display a list of objects with the built-in adapter

Objects with attributes id, label, and children (set to a list) can be dealt with automatically by the built-in lov adapter of the tree control.

Assuming your Python code has created a list of such objects:

class User:
    def __init__(self, id, label, birth_year, children):
        self.id, self.label, self.birth_year, self.children = (id, label, birth_year, children)

users = [
    User(231, "Johanna", 1987, [User(231.1, "Johanna's son", 2006, [])]),
    User(125, "John",    1979, []),
    User(4,   "Peter",   1968, []),
    User(31,  "Mary",    1974, [])
    ]

user_sel = users[2]

If you want to create a tree control that lets users pick a specific user, you can use the following control definition:

Definition

<|{user_sel}|tree|lov={users}|>
<taipy:tree lov="{users}">{user_sel}</taipy:tree>
import taipy.gui.builder as tgb
...
tgb.tree("{user_sel}", lov="{users}")

Display a hierarchy of arbitrary objects

The adapter property can be set to a function that transforms an arbitrary object to a representation that the tree control can use: a tuple where the first element is an identifier of the object (used in the value property), the second element represents the item's label, and the third element is a list to child objects.

Assuming your Python code has created a list of objects:

class User:
    def __init__(self, id, name, birth_year, children):
        self.id, self.name, self.birth_year, self.children = (id, name, birth_year, children)

users = [
    User(231, "Johanna", 1987, [User(231.1, "Johanna's son", 2006, [])]),
    User(125, "John",    1979, []),
    User(4,   "Peter",   1968, []),
    User(31,  "Mary",    1974, [])
    ]

user_sel = users[2]

In this example, we use the Python list users as the tree's list of values. Because the control needs a way to convert the list items (which are instances of the class User) into a string that can be displayed, we are using an adapter: a function that converts an object whose type must be provided to the type property to a tuple.

In our situation, the adapter can be a lambda function that returns the adapted tuple for each object in the hierarchy:

Definition

<|{user_sel}|tree|lov={users}|type=User|adapter={lambda u: (u.id, u.name, u.children)}|>
<taipy:tree lov="{users}" type="User" adapter="{lambda u: (u.id, u.name, u.children)}">{user_sel}</taipy:tree>
import taipy.gui.builder as tgb
...
tgb.tree("{user_sel}", lov="{users}", type="User", adapter="{lambda u: (u.id, u.name, u.children)}")