Tree

ic.Tree is a hierarchical list component that renders nested nodes with expand/collapse folders, optional selection checkboxes, and connector lines. It extends ic.TreeBase, which provides shared tree infrastructure: the Items property (an array of ic.tree.Node objects), Value / Selection for tracking which nodes are selected, incremental node operations (addNode, removeNode, updateNode), and programmatic expand/collapse control.

Building the tree

Tree is driven by an array of ic.tree.Node objects. Each node has a Label, an optional Icon (any Lucide icon name or ic.Asset), and optional Children. Folder nodes are simply nodes that have children. You build the hierarchy by calling .add() on a parent node, which creates and attaches a child and returns it so you can keep nesting.

% Build the tree using ic.tree.Node
% Each node has a Label, optional Icon, and optional Data payload.
% Children are added with the .add() method, which returns the new node.

citrus = ic.tree.Node("Citrus", Icon="citrus");
citrus.add("Orange", Icon="circle");
citrus.add("Lemon", Icon="circle");
citrus.add("Lime", Icon="circle");

berries = ic.tree.Node("Berries", Icon="cherry");
berries.add("Strawberry", Icon="heart");
berries.add("Blueberry", Icon="heart");

tropical = ic.tree.Node("Tropical", Icon="palm-tree");
tropical.add("Mango", Icon="sun");
exotic = tropical.add("Exotic", Icon="sparkles");
exotic.add("Dragon Fruit", Icon="star");
exotic.add("Passion Fruit", Icon="star");

% Pass the root nodes as an array to Items
tree = ic.Tree();
tree.Items = [citrus, berries, tropical];

% BAD: reassigning Items re-serializes the entire tree,
%      resets the selection, and rebuilds the whole view.
tree.Items = [citrus, berries, tropical];  % full rebuild

% GOOD: use incremental methods instead.
% They publish only the changed node to the view.

% Add a node under a parent (or pass empty for a new root)
[grape, ~] = tree.addNode(citrus, "Grapefruit", Icon="citrus");
[root, ~]  = tree.addNode(ic.tree.Node.empty, "Stone Fruits");

% Update a node label or icon in place
tree.updateNode(grape, Label="Pink Grapefruit");
tree.updateNode(grape, Icon="heart");

% Remove a node (clears its key from Value automatically)
tree.removeNode(grape);

Size, connector lines, and height

Size scales the font, row height, and indentation: sm for compact lists, md (default) for general use, and lg for touch-friendly or prominent trees. ShowLine toggles the vertical and branch connector lines that visually link parent nodes to their children. Connector lines help the eye trace depth in large hierarchies, but for shallow trees you may prefer the cleaner look without them. Height sets the scrollable area in pixels (or as a CSS string like "50vh"), with a default of 400px.

Selection

Setting Selectable to true (the default) shows checkboxes next to each node, letting the user build a multi-selection. MaxSelectedItems caps how many nodes can be selected at once: once the limit is reached, remaining checkboxes become unresponsive until something is deselected. Disabled greys out the entire tree and prevents any interaction.

The Selection property on the MATLAB side returns an array of ic.tree.Node handles for the currently selected nodes, which is usually more useful than the raw positional key strings in Value.

Events

Tree fires ValueChanged whenever the user checks or unchecks a node, carrying the current array of selected positional keys. SelectionChanged is a convenience event that fires alongside it, but with resolved ic.tree.Node handles instead of raw key strings. Click some checkboxes below to see both events in the log.

Expand and collapse

Tree exposes expandAll(), collapseAll(), expandNode(node), and collapseNode(node) for programmatic control over which folders are open. expandNode also opens all ancestor folders so the target node becomes visible. clearSelection() deselects everything.

Custom styling

Every component exposes a .css property for instance-level CSS overrides from MATLAB.

tree = ic.Tree("Items", [root1, root2]);

% Tropical gradient background
tree.css.style(".ic-tree", ...
    "background", "linear-gradient(135deg, #fdf2f8, #fce7f3, #e0f2fe, #ccfbf1)", ...
    "border_color", "#f0abfc", ...
    "border_radius", "8px");

tree.css.style(".ic-tn__icon", ...
    "color", "#0ea5e9");

% Gradient tree lines
tree.css.style(".ic-tn__guide--pipe::before", ...
    "background", "linear-gradient(to bottom, #7dd3fc, #bae6fd)");
tree.css.style(".ic-tn__guide--branch::before", ...
    "background", "linear-gradient(to bottom, #7dd3fc, #bae6fd)");
tree.css.style(".ic-tn__guide--branch::after", ...
    "background", "#7dd3fc");

% Sliding left-accent on hover via ::before
tree.css.style(".ic-tn__row", ...
    "position", "relative");
tree.css.style(".ic-tn__row::before", ...
    "content", """""", ...
    "position", "absolute", ...
    "left", "0", "top", "0", "bottom", "0", ...
    "width", "3px", ...
    "background", "#0284c7", ...
    "transform", "scaleY(0)", ...
    "transition", "transform 0.15s ease");
tree.css.style(".ic-tn__row:hover::before", ...
    "transform", "scaleY(1)");
tree.css.style(".ic-tn__row:hover", ...
    "background", "rgba(14, 165, 233, 0.06)");

% Hide the folder icon
tree.css.style(".ic-tn__folder", ...
    "display", "none");

% Glowing selected items
tree.css.style(".ic-tn__content--selected", ...
    "background", "rgba(14, 165, 233, 0.12)", ...
    "border_radius", "4px", ...
    "box_shadow", "0 0 8px rgba(14, 165, 233, 0.3)");