ui.tree | NiceGUI

ui.tree

Tree

Display hierarchical data using Quasar's QTree component.

If using IDs, make sure they are unique within the whole tree.

To use checkboxes and on_tick, set the tick_strategy parameter to "leaf", "leaf-filtered" or "strict".

nodes:	hierarchical list of node objects
node_key:	property name of each node object that holds its unique id (default: "id")
label_key:	property name of each node object that holds its label (default: "label")
children_key:	property name of each node object that holds its list of children (default: "children")
on_select:	callback which is invoked when the node selection changes
on_expand:	callback which is invoked when the node expansion changes
on_tick:	callback which is invoked when a node is ticked or unticked
tick_strategy:	whether and how to use checkboxes ("leaf", "leaf-filtered" or "strict"; default: `None`)

main.py

from nicegui import ui

ui.tree([
    {'id': 'numbers', 'children': [{'id': '1'}, {'id': '2'}]},
    {'id': 'letters', 'children': [{'id': 'A'}, {'id': 'B'}]},
], label_key='id', on_select=lambda e: ui.notify(e.value))

ui.run()

NiceGUI

Tree with custom header and body

Scoped slots can be used to insert custom content into the header and body of a tree node. See the Quasar documentation for more information.

main.py

from nicegui import ui

tree = ui.tree([
    {'id': 'numbers', 'description': 'Just some numbers', 'children': [
        {'id': '1', 'description': 'The first number'},
        {'id': '2', 'description': 'The second number'},
    ]},
    {'id': 'letters', 'description': 'Some latin letters', 'children': [
        {'id': 'A', 'description': 'The first letter'},
        {'id': 'B', 'description': 'The second letter'},
    ]},
], label_key='id', on_select=lambda e: ui.notify(e.value))

tree.add_slot('default-header', '''
    <span :props="props">Node <strong>{{ props.node.id }}</strong></span>
''')
tree.add_slot('default-body', '''
    <span :props="props">Description: "{{ props.node.description }}"</span>
''')

ui.run()

NiceGUI

Tree with checkboxes

The tree can be used with checkboxes by setting the "tick-strategy" prop.

main.py

from nicegui import ui

ui.tree([
    {'id': 'A', 'children': [{'id': 'A1'}, {'id': 'A2'}]},
    {'id': 'B', 'children': [{'id': 'B1'}, {'id': 'B2'}]},
], label_key='id', tick_strategy='leaf', on_tick=lambda e: ui.notify(e.value))

ui.run()

NiceGUI

Expand/collapse programmatically

The whole tree or individual nodes can be toggled programmatically using the expand() and collapse() methods. This even works if a node is disabled (e.g. not clickable by the user).

main.py

from nicegui import ui

t = ui.tree([
    {'id': 'A', 'children': [{'id': 'A1'}, {'id': 'A2'}], 'disabled': True},
    {'id': 'B', 'children': [{'id': 'B1'}, {'id': 'B2'}]},
], label_key='id').expand()

with ui.row():
    ui.button('+ all', on_click=t.expand)
    ui.button('- all', on_click=t.collapse)
    ui.button('+ A', on_click=lambda: t.expand(['A']))
    ui.button('- A', on_click=lambda: t.collapse(['A']))

ui.run()

NiceGUI

Select/deselect programmatically

You can select or deselect nodes with the select() and deselect() methods.

main.py

from nicegui import ui

t = ui.tree([
    {'id': 'numbers', 'children': [{'id': '1'}, {'id': '2'}]},
    {'id': 'letters', 'children': [{'id': 'A'}, {'id': 'B'}]},
], label_key='id').expand()

with ui.row():
    ui.button('Select A', on_click=lambda: t.select('A'))
    ui.button('Deselect A', on_click=t.deselect)

ui.run()

NiceGUI

Tick/untick programmatically

After setting a tick_strategy, you can tick or untick nodes with the tick() and untick() methods. You can either specify a list of node keys or None to tick or untick all nodes.

main.py

from nicegui import ui

t = ui.tree([
    {'id': 'numbers', 'children': [{'id': '1'}, {'id': '2'}]},
    {'id': 'letters', 'children': [{'id': 'A'}, {'id': 'B'}]},
], label_key='id', tick_strategy='leaf').expand()

with ui.row():
    ui.button('Tick 1, 2 and B', on_click=lambda: t.tick(['1', '2', 'B']))
    ui.button('Untick 2 and B', on_click=lambda: t.untick(['2', 'B']))
with ui.row():
    ui.button('Tick all', on_click=t.tick)
    ui.button('Untick all', on_click=t.untick)

ui.run()

NiceGUI

Filter nodes

You can filter nodes by setting the filter property. The tree will only show nodes that match the filter.

main.py

from nicegui import ui

t = ui.tree([
    {'id': 'fruits', 'children': [{'id': 'Apple'}, {'id': 'Banana'}]},
    {'id': 'vegetables', 'children': [{'id': 'Potato'}, {'id': 'Tomato'}]},
], label_key='id').expand()
ui.input('filter').bind_value_to(t, 'filter')

ui.run()

NiceGUI

Reference

Initializer

nodes:hierarchical list of node objects
node_key:property name of each node object that holds its unique id (default: "id")
label_key:property name of each node object that holds its label (default: "label")
children_key:property name of each node object that holds its list of children (default: "children")
on_select:callback which is invoked when the node selection changes
on_expand:callback which is invoked when the node expansion changes
on_tick:callback which is invoked when a node is ticked or unticked
tick_strategy:whether and how to use checkboxes ("leaf", "leaf-filtered" or "strict"; default: None)

Properties

classes: 'Classes[Self]'

The classes of the element.

filter: BindableProperty

is_deleted: 'bool'

Whether the element has been deleted.

is_ignoring_events: 'bool'

Return whether the element is currently ignoring events.

props: 'Props[Self]'

The props of the element.

style: 'Style[Self]'

The style of the element.

visible: BindableProperty

Methods

add_resource(path: Union[str, Path]) -> None

Add a resource to the element.

param path:	path to the resource (e.g. folder with CSS and JavaScript files)

add_slot(name: str, template: Optional[str] = None) -> Slot

Add a slot to the element.

NiceGUI is using the slot concept from Vue: Elements can have multiple slots, each possibly with a number of children. Most elements only have one slot, e.g. a ui.card (QCard) only has a default slot. But more complex elements like ui.table (QTable) can have more slots like "header", "body" and so on. If you nest NiceGUI elements via with ui.row(): ... you place new elements inside of the row's default slot. But if you use with table.add_slot(...): ..., you enter a different slot.

The slot stack helps NiceGUI to keep track of which slot is currently used for new elements. The parent field holds a reference to its element. Whenever an element is entered via a with expression, its default slot is automatically entered as well.

param name:	name of the slot
param template:	Vue template of the slot
return:	the slot

ancestors(include_self: bool = False) -> Iterator[Element]

Iterate over the ancestors of the element.

param include_self:
	whether to include the element itself in the iteration

bind_filter(target_object: Any, target_name: str = 'filter', forward: Callable[..., Any] = [...], backward: Callable[..., Any] = [...]) -> Self

Bind the filter of this element to the target object's target_name property.

The binding works both ways, from this element to the target and from the target to this element. The update happens immediately and whenever a value changes. The backward binding takes precedence for the initial synchronization.

param target_object:
	The object to bind to.
param target_name:
	The name of the property to bind to.
param forward:	A function to apply to the value before applying it to the target.
param backward:	A function to apply to the value before applying it to this element.

bind_filter_from(target_object: Any, target_name: str = 'filter', backward: Callable[..., Any] = [...]) -> Self

Bind the filter of this element from the target object's target_name property.

The binding works one way only, from the target to this element. The update happens immediately and whenever a value changes.

param target_object:
	The object to bind from.
param target_name:
	The name of the property to bind from.
param backward:	A function to apply to the value before applying it to this element.

bind_filter_to(target_object: Any, target_name: str = 'filter', forward: Callable[..., Any] = [...]) -> Self

Bind the filter of this element to the target object's target_name property.

The binding works one way only, from this element to the target. The update happens immediately and whenever a value changes.

param target_object:
	The object to bind to.
param target_name:
	The name of the property to bind to.
param forward:	A function to apply to the value before applying it to the target.

bind_visibility(target_object: Any, target_name: str = 'visible', forward: Callable[..., Any] = [...], backward: Callable[..., Any] = [...], value: Any = None) -> Self

Bind the visibility of this element to the target object's target_name property.

param target_object:
	The object to bind to.
param target_name:
	The name of the property to bind to.
param forward:	A function to apply to the value before applying it to the target.
param backward:	A function to apply to the value before applying it to this element.
param value:	If specified, the element will be visible only when the target value is equal to this value.

bind_visibility_from(target_object: Any, target_name: str = 'visible', backward: Callable[..., Any] = [...], value: Any = None) -> Self

Bind the visibility of this element from the target object's target_name property.

The binding works one way only, from the target to this element. The update happens immediately and whenever a value changes.

param target_object:
	The object to bind from.
param target_name:
	The name of the property to bind from.
param backward:	A function to apply to the value before applying it to this element.
param value:	If specified, the element will be visible only when the target value is equal to this value.

bind_visibility_to(target_object: Any, target_name: str = 'visible', forward: Callable[..., Any] = [...]) -> Self

Bind the visibility of this element to the target object's target_name property.

The binding works one way only, from this element to the target. The update happens immediately and whenever a value changes.

param target_object:
	The object to bind to.
param target_name:
	The name of the property to bind to.
param forward:	A function to apply to the value before applying it to the target.

clear() -> None

Remove all child elements.

collapse(node_keys: Optional[List[str]] = None) -> Self

Collapse the given nodes.

param node_keys:
	list of node keys to collapse (default: all nodes)

default_classes(add: Optional[str] = None, remove: Optional[str] = None, toggle: Optional[str] = None, replace: Optional[str] = None) -> type[Self]

Apply, remove, toggle, or replace default HTML classes.

This allows modifying the look of the element or its layout using Tailwind or Quasar classes.

Removing or replacing classes can be helpful if predefined classes are not desired. All elements of this class will share these HTML classes. These must be defined before element instantiation.

param add:	whitespace-delimited string of classes
param remove:	whitespace-delimited string of classes to remove from the element
param toggle:	whitespace-delimited string of classes to toggle (added in version 2.7.0)
param replace:	whitespace-delimited string of classes to use instead of existing ones

default_props(add: Optional[str] = None, remove: Optional[str] = None) -> type[Self]

Add or remove default props.

This allows modifying the look of the element or its layout using Quasar props. Since props are simply applied as HTML attributes, they can be used with any HTML element. All elements of this class will share these props. These must be defined before element instantiation.

Boolean properties are assumed True if no value is specified.

param add:	whitespace-delimited list of either boolean values or key=value pair to add
param remove:	whitespace-delimited list of property keys to remove

default_style(add: Optional[str] = None, remove: Optional[str] = None, replace: Optional[str] = None) -> type[Self]

Apply, remove, or replace default CSS definitions.

Removing or replacing styles can be helpful if the predefined style is not desired. All elements of this class will share these CSS definitions. These must be defined before element instantiation.

param add:	semicolon-separated list of styles to add to the element
param remove:	semicolon-separated list of styles to remove from the element
param replace:	semicolon-separated list of styles to use instead of existing ones

delete() -> None

Delete the element and all its children.

descendants(include_self: bool = False) -> Iterator[Element]

Iterate over the descendants of the element.

param include_self:
	whether to include the element itself in the iteration

deselect() -> Self

Remove node selection.

expand(node_keys: Optional[List[str]] = None) -> Self

Expand the given nodes.

param node_keys:
	list of node keys to expand (default: all nodes)

get_computed_prop(prop_name: str, timeout: float = 1) -> AwaitableResponse

Return a computed property.

This function should be awaited so that the computed property is properly returned.

param prop_name:
	name of the computed prop
param timeout:	maximum time to wait for a response (default: 1 second)

mark(*markers: str) -> Self

Replace markers of the element.

Markers are used to identify elements for querying with ElementFilter which is heavily used in testing but can also be used to reduce the number of global variables or passing around dependencies.

param markers:	list of strings or single string with whitespace-delimited markers; replaces existing markers

move(target_container: Optional[Element] = None, target_index: int = -1, target_slot: Optional[str] = None) -> None

Move the element to another container.

param target_container:
	container to move the element to (default: the parent container)
param target_index:
	index within the target slot (default: append to the end)
param target_slot:
	slot within the target container (default: default slot)

on(type: str, handler: Optional[events.Handler[events.GenericEventArguments]] = None, args: Union[None, Sequence[str], Sequence[Optional[Sequence[str]]]] = None, throttle: float = 0.0, leading_events: bool = True, trailing_events: bool = True, js_handler: Optional[str] = None) -> Self

Subscribe to an event.

param leading_events:
param type:	name of the event (e.g. "click", "mousedown", or "update:model-value")
param handler:	callback that is called upon occurrence of the event
param args:	arguments included in the event message sent to the event handler (default: None meaning all)
param throttle:	minimum time (in seconds) between event occurrences (default: 0.0)
	whether to trigger the event handler immediately upon the first event occurrence (default: True)
param trailing_events:
	whether to trigger the event handler after the last event occurrence (default: True)
param js_handler:
	JavaScript code that is executed upon occurrence of the event, e.g. (evt) => alert(evt) (default: None)

on_expand(callback: Union[Callable[[nicegui.events.ValueChangeEventArguments], Any], Callable[[], Any]]) -> Self

Add a callback to be invoked when the expansion changes.

on_select(callback: Union[Callable[[nicegui.events.ValueChangeEventArguments], Any], Callable[[], Any]]) -> Self

Add a callback to be invoked when the selection changes.

on_tick(callback: Union[Callable[[nicegui.events.ValueChangeEventArguments], Any], Callable[[], Any]]) -> Self

Add a callback to be invoked when a node is ticked or unticked.

remove(element: Union[Element, int]) -> None

Remove a child element.

param element:	either the element instance or its ID

run_method(name: str, *args: Any, timeout: float = 1) -> AwaitableResponse

Run a method on the client side.

If the function is awaited, the result of the method call is returned. Otherwise, the method is executed without waiting for a response.

param name:	name of the method
param args:	arguments to pass to the method
param timeout:	maximum time to wait for a response (default: 1 second)

select(node_key: Optional[str]) -> Self

Select the given node.

param node_key:	node key to select

set_filter(filter_: str) -> None

Set the filter of this element.

param filter:	The new filter.

set_visibility(visible: bool) -> None

Set the visibility of this element.

param visible:	Whether the element should be visible.

tick(node_keys: Optional[List[str]] = None) -> Self

Tick the given nodes.

param node_keys:
	list of node keys to tick or `None` to tick all nodes (default: `None`)

tooltip(text: str) -> Self

Add a tooltip to the element.

param text:	text of the tooltip

untick(node_keys: Optional[List[str]] = None) -> Self

Remove tick from the given nodes.

param node_keys:
	list of node keys to untick or `None` to untick all nodes (default: `None`)

update() -> None

Update the element on the client side.

Inheritance

FilterElement
Element
Visibility