Reference API

streamlit_arborist.tree_view(data: List[dict], icons: Dict[str, str] = None, row_height: int = 24, width: int | str = 'auto', height: int = 500, indent: int = 24, overscan_count: int = 1, padding_top: int = None, padding_bottom: int = None, padding: int = None, children_accessor: str = 'children', id_accessor: str = 'id', open_by_default: bool = True, selection: str = None, select_internal_nodes: bool = False, initial_open_state: Dict[str, bool] = None, search_term: str = None, key: str | int = None, on_change: Callable[[...], None] = None) → dict | None[source]

Display a tree view.

Parameters

datalist of dict

A list of dictionaries representing the tree data. Each dictionary must have an id key. Optional keys are name for display (otherwise uses id), and children for child nodes.

iconsdict, optional

A dict of keys "open", "closed", and "leaf" with string values representing the icons to use for open internal nodes, closed internal nodes, and leaf nodes, respectively.

The following options are valid values:

  • A single-character emoji. For example, you can set icons={"open": "πŸ”“", "closed": "πŸ”’", "leaf": "πŸ€"}. Emoji short codes are not supported.

  • An icon from the Material Symbols library (rounded style) in the format ":material/icon_name:" where icon_name is the name of the icon in snake case.

row_heightint, default 24

Height of each row in pixels.

widthint or str, default β€œauto”

View width in pixels or a valid CSS width string.

heightint, default 500

View height in pixels.

indentint, default 24

Node indentation in pixels.

overscan_countint, default 1

Number of additional rows rendered outside the visible viewport to ensure smooth scrolling and better performance.

padding_topint, optional

Space between the tree and its top border, in pixels.

padding_bottomint, optional

Space between the tree and its bottom border, in pixels.

paddingint, optional

Space between the tree and its top/bottom borders, in pixels. Overrides both padding_top and padding_bottom.

children_accessorstr, default β€œchildren”

The children key in the tree data.

id_accessorstr, default β€œid”

The ID key in the tree data.

open_by_defaultbool, default True

Whether all nodes should be open when rendered.

selectionstr or int, optional

The node id to select and scroll when rendered.

select_internal_nodesbool, default False

If False, clicking an internal node only toggles open/closed. If True, internal (non-leaf) nodes can be selected:

  • Single-click the icon to toggle open/closed

  • Single-click the label to select

  • Double-click the label to select and toggle

initial_open_stateDict[str, bool], optional

A dict of node ID keys and bool values indicating whether the node is open (True) or closed (False) when rendered.

search_termstr, optional

Only show nodes that match search_term. If a child matches, all its parents also match. Internal nodes are opened when filtering.

keystr, optional

An optional string or integer to use as the unique key for the widget. If this is omitted, a key will be generated for the widget based on its content. Multiple widgets of the same type may not share the same key.

on_changecallable, optional

An optional callback invoked when a node is selected. No arguments are passed to it.

Returns

dict or None

The data of the selected node. Returns None if no node is selected.

Examples

The data should be a list of dictionaries, where each dictionary represents a node in the tree. Each node should have the following keys:

  • id (required)

  • name: string to display (optional), and

  • children: list of nested nodes (optional)

Nodes without children key are considered leafs.

>>> data = [
...     {
...         "id": "1",
...         "name": "Parent 1",
...         "children": [
...             {"id": "1.1", "name": "Child 1"},
...             {"id": "1.2", "name": "Child 2"}
...         ]
...     },
...     {
...         "id": "2",
...         "name": "Parent 2",
...         "children": [
...             {"id": "2.1", "name": "Child 3"},
...             {"id": "2.2", "name": "Child 4"}
...         ]
...     }
... ]

>>> from streamlit_arborist import tree_view
>>> tree_view(data)