Usage

streamlit-arborist is mostly a wrapper around react-arborist. Note that not every feature from react-arborist is available in streamlit-arborist.

It exposes two custom components:

  • tree_view(): display a tree and let the user pick one node. Use when the user picks a single node, e.g. file pickers or navigation

  • tree_checkbox(): display a tree with a checkbox per row for multi-selection with cascading. Use when the user picks a set of nodes, e.g. picking categories or selecting items for a downstream operation.

Both components share almost all parameters, including appearance and search options.

See also

See all available parameters in the Reference API.

Data

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)

from streamlit_arborist import tree_view

data = [
    {
        "id": "1",
        "name": "Child 1",
    },
    {
        "id": "2",
        "name": "Parent 2",
        "children": [
            {"id": "2.1", "name": "Child 2.1"},
            {"id": "2.2", "name": "Child 2.2"}
        ]
    }
]

tree_view(data)

You may include additional keys in the node’s data:

data2 = [
    {"id": "1", "name": "Node 1", "description": "This is node 1"},
    {"id": "2", "name": "Node 2", "description": "This is node 2"}
]

tree_view(data2)

Change the default key names using children_accessor and id_accessor.

data3 = [{"key": "A", "contents": [{"key": "A.1"}, {"key": "A.2"}]}]
tree_view(data3, children_accessor="contents", id_accessor="key")

Single selection (tree_view)

tree_view() allows selecting leaf nodes by clicking on them. The component returns the selected node’s data, including extra keys.

>>> selected = tree_view(data)
>>> selected
{"id": "1.1", "name": "Child 1"}

Row interaction:

  • Click a leaf node to select it.

  • Click an internal node to toggle open/closed.

  • Use arrow keys and space to interact via the keyboard.

Programmatically select a node by passing its id:

tree_view(data, selection="2.1")

Set select_internal_nodes=True to allow the selection of internal nodes. The behavior of internal nodes changes:

  • Click the icon to toggle open/closed

  • Click the label to select

  • Double-click the label to select and toggle

Selecting an internal node returns the node’s data, including the children key.

>>> selected = tree_view(data, select_internal_nodes=True)
>>> selected
{
    "id": "2",
    "name": "Parent 2",
    "children": [
        {"id": "2.1", "name": "Child 2.1"},
        {"id": "2.2", "name": "Child 2.2"}
    ]
}

Checkbox multi-selection (tree_checkbox)

Use tree_checkbox() allow users to select multiple nodes with checkboxes. The component returns a list of fully-checked node IDs.

Checking an internal node cascades down to its children, and a node whose children are only partially checked renders as indeterminate.

from streamlit_arborist import tree_checkbox

tree_checkbox(data)

Row interaction:

  • Click the chevron at the start of an internal row to open/close (does not change the check state).

  • Click anywhere on a row (or its checkbox) to toggle the check. Internal nodes cascade to all children.

  • Double-click an internal row to toggle the check and open/close in one gesture.

  • Press space on a focused row to toggle the check via the keyboard.

Set the initial checked state with the checked argument:

>>> checked = tree_checkbox(data, checked=["1.1"])
>>> checked
['1.1']

Including an internal node auto-checks its children, so the returned list may be a superset of what you passed in:

>>> checked = tree_checkbox(data, checked=["1"])
>>> checked
['1', '1.1', '1.2']

Note

The checked argument is applied only on the initial render. Passing a different list on subsequent Streamlit reruns does not overwrite the user’s interactive state. To reset the widget, pass a new key.

Appearance

Set icons for open/closed internal nodes and leaf nodes using the icons parameter.

tree_view(data, icons={"open": "📂", "closed": "📁", "leaf": "📄"})

Material Symbols icons are also supported.

tree_view(
    data,
    icons={
        "open": ":material/folder_open:",
        "closed": ":material/folder:",
        "leaf": ":material/docs:"
    }
)

Customize sizes and padding:

tree_view(
    data,
    row_height=30,
    height=400,
    padding_top=10,
)