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 |
---|---|---|---|
(★) |
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 |
select_leafs_only |
bool |
False | If True, the user can only select leaf nodes. |
row_height |
str |
The height of each row of this tree, in CSS units. |
|
label |
str |
None | The label associated with the selector when in dropdown mode. |
mode |
str |
Define the way the selector is displayed:
|
|
dropdown |
bool |
False | If True, the list of items is shown in a dropdown menu. |
filter |
bool |
False | If True, this control is combined with a filter input area. |
width |
Union[str,int] |
"360px" | The width of this selector, in CSS units. |
height |
Union[str,int] |
The height of this 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]). |
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).
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 is updated.
|
|
propagate |
bool |
App config | Allows the control's main value to be automatically propagated. |
active |
bool dynamic |
True | Indicates if this component is active. |
id |
str |
The identifier that is 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 are associated with the generated HTML Element. |
|
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.
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)")
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.