anycomplextree

An anywidget that wraps react-complex-tree, giving you an interactive tree view inside Jupyter / JupyterLab / VS Code / Marimo notebooks with two-way state sync to Python.

Features

• Hierarchical tree rendering powered by react-complex-tree
• Two-way sync for selection, expansion, and focus
• Python-side validation of tree structure with clear error messages
• Single bundled ESM asset — no CDN fetches at runtime

Installation

uv add anycomplextree

Quick start

from anycomplextree import ComplexTree

tree = ComplexTree(
    items={
        "root": {
            "isFolder": True,
            "children": ["fruits", "meals"],
            "data": "Root",
        },
        "fruits": {
            "isFolder": True,
            "children": ["apple", "orange", "banana"],
            "data": "Fruits",
        },
        "apple":  {"data": "Apple"},
        "orange": {"data": "Orange"},
        "banana": {"data": "Banana"},
        "meals": {
            "isFolder": True,
            "children": ["pasta", "pizza"],
            "data": "Meals",
        },
        "pasta": {"data": "Pasta"},
        "pizza": {"data": "Pizza"},
    },
    root_item="root",
)
tree

The items model

Each entry in items represents one node. The dict key is the node's identifier — react-complex-tree calls it index. The key, the optional index field on the item, and the entries inside parent children arrays must all be the same string.

Using UUIDs

Since the dict key is the identifier, just use UUID strings as keys:

import uuid
apple_id = str(uuid.uuid4())
fruits_id = str(uuid.uuid4())

tree = ComplexTree(
    items={
        fruits_id: {"isFolder": True, "children": [apple_id], "data": "Fruits"},
        apple_id:  {"data": "Apple"},
        "root":    {"isFolder": True, "children": [fruits_id], "data": "Root"},
    },
)

tree.selected_items  # -> [apple_id] after you click Apple

Traits

All traits are two-way synced between Python and the browser.

Read, write, or observe them like any traitlet:

tree.expanded_items = ["root", "fruits"]
tree.selected_items = ["apple"]
tree.focused_item   = "apple"

tree.observe(lambda change: print("selection:", change["new"]), names="selected_items")

Note: traitlets only fires change events when the trait is reassigned, not when mutated in place. Use tree.selected_items = [...], not tree.selected_items.append(...).

Validation

items and root_item are validated on assignment. You'll get a TraitError with a clear message for:

• A dict key that doesn't match an explicit index field
• A children entry that doesn't exist in items
• A root_item that isn't a key in items

Development

The widget bundle lives in js/ and builds to anycomplextree/static/.

# one-time install
cd js && npm install

# rebuild after JS changes
npm run build

# watch mode during development
npm run dev

On the Python side:

uv sync
uv run jupyter lab

License

MIT