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`	`Union[bool, list[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 of each row of the tree, in CSS units.
`label`	`str`	None	The label associated with the selector when in dropdown mode.
`selection_message`	`str` dynamic		The message shown in the selection area of a dropdown selector when at least one element is selected. If None, the message is the list of all the selected elements.
`show_select_all`	`bool`	False	If True and multiple is True, the selector shows a "Select all option" button.
`filter`	`bool`	False	If True, this control is combined with a filter input area.
`width`	`Union[str, int]`	"360px"	The width of the selector, in CSS units.
`height`	`Union[str, int]`		The height of the selector, in CSS units.
`lov`	`dict[str, Any]`		The list of values. See the section on List of Values for more details.
`adapter`	`Union[str, Callable]`	`lambda x: str(x)`	A function or the name of the function that transforms an element of lov into a tuple(id:str, label:Union[str, Icon]). The default value is a function that returns the string representation of the lov element.
`type`	`str`	Type name of the first lov element	This property is required if lov contains a non-specific type of data (e.g., a dictionary). Then: value must be of that type lov must be an iterable containing elements of this type The function set to adapter will receive an object of this type. The default value is the type of the first element in lov.
`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`	`Union[str, Callable]`		A function or the name of a function that is triggered when the value changes. The callback function receives the following parameters: state (`State`): the state instance. var_name (str): the bound variable name. value (Any): the updated value.
`propagate`	`bool`	App config	Determines whether the control's value is automatically reflected in the bound application variable. The default value is defined at the application configuration level by the propagate configuration option. If True, any change to the control's value is immediately reflected in the variable.
`active`	`bool` dynamic	True	Indicates if this element is active. If False, the element is disabled, and user interaction is not allowed.
`id`	`str`		The identifier assigned to the rendered HTML component. This can be used in callbacks or to target the element for styling.
`properties`	`dict[str, Any]`		A dictionary of additional properties that can be set to the element.
`class_name`	`str` dynamic		A space-separated list of CSS class names to be applied to the generated HTML element. These classes are added to the default `taipy-tree` class.
`hover_text`	`str` dynamic		The text that is displayed when the user hovers over the element.

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

Usage¶

Display a list of string¶

You can create a tree on a series of strings:

Definition

MarkdownHTMLPython

<|{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

MarkdownHTMLPython

<|{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

MarkdownHTMLPython

<|{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

MarkdownHTMLPython

<|{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

MarkdownHTMLPython

<|{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

MarkdownHTMLPython

<|{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

MarkdownHTMLPython

<|{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)")

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.