TreeSelect

ic.TreeSelect is a hierarchical multi-value selector that displays cascading sub-menus for navigating a tree structure. Selected leaf nodes appear as closable tags inside the input field. It extends ic.TreeBase, which provides shared tree node management (Items, Value, Selection), incremental node operations (addNode, removeNode, updateNode), and expand/collapse control.

Building the tree

TreeSelect is driven by an array of ic.tree.Node objects. Each node has a Label, an optional Icon, 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");
citrus.add("Lemon");
citrus.add("Lime");

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

tropical = ic.tree.Node("Tropical", Icon="palmtree");
tropical.add("Mango");
exotic = tropical.add("Exotic");   % nested folder
exotic.add("Dragon Fruit");
exotic.add("Passion Fruit");

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

Variants

Variant controls the visual style of the trigger field. The primary variant has a visible border, while secondary uses a filled background with no visible border for less visual weight in dense layouts.

Size

Size scales the trigger field, tags, and dropdown text together. The three options are sm, md, and lg.

Clearable and hover expansion

When Clearable is true, a small clear button appears in the trigger field after items are selected, letting the user reset to “no selection” in one click. When OpenOnHover is true, hovering over a folder row automatically opens its sub-panel instead of requiring a chevron click.

Max selected items

MaxSelectedItems limits how many leaf nodes can be selected at a time. Once the limit is reached, unselected items become disabled. Set it to Inf (the default) for unlimited selection.

Popup dimensions

MaxPopupHeight controls the maximum height of each cascade panel (default 200px). MaxPanelWidth controls the maximum width of each panel (default 240px). Both accept pixels or CSS size strings.

Incremental updates

Setting Items directly re-serializes the entire tree to the frontend, resets the selection, and forces a full rebuild of the view. For trees with many nodes this is wasteful and causes a visible flash. The incremental methods (addNode, removeNode, updateNode) publish only the changed node to the view, keeping the rest of the tree, the selection, and the expanded/collapsed state intact.

Use addNode to insert a single node under any parent (or pass ic.tree.Node.empty as the parent to create a new root). updateNode patches a node’s label or icon without touching its position or children. removeNode detaches a node and automatically cleans up any selected keys that pointed at it or its descendants. All three return the result from the view so you can confirm the operation landed.

% BAD: reassigning Items re-serializes the entire tree,
%      resets the selection, and rebuilds the whole view.
ts.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, ~] = ts.addNode(citrus, "Grapefruit", Icon="citrus");
[root, ~]  = ts.addNode(ic.tree.Node.empty, "Stone Fruits");

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

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

Dropdown control

open and close let you programmatically toggle the dropdown. clearSelection resets the selection to empty and fires ValueChanged with null.

Expand and collapse

expandAll opens every folder node in the tree at once. collapseAll closes them all. These are useful when you want to let the user quickly browse or reset the tree hierarchy.

Events

TreeSelect fires three events from the UI. ValueChanged triggers when the user selects or deselects a leaf node, carrying the updated value array (or null when cleared) in evt.Data.value. Opened and Closed fire when the dropdown opens and closes. The inherited SelectionChanged event fires automatically when Value changes and carries the resolved ic.tree.Node handles.

Custom styling

Every component exposes a .css property that lets you inject instance-level CSS directly from MATLAB. This example creates a green theme. The selectors target .ic-ts__field for the trigger, .ic-tag for selected-item pills, .ic-tp__panel for cascade backgrounds, and .ic-tp__row / .ic-tp__check for row interactions.

ts = ic.TreeSelect("Items", [root1, root2]);
ts.Placeholder = "Pick from garden...";

% Pale mint field with green border
ts.css.style(".ic-ts__field", ...
    "background", "#f0fdf4", ...
    "border_color", "#86efac", ...
    "color", "#14532d", ...
    "box_shadow", "inset 0 1px 4px rgba(34, 197, 94, 0.1)");

ts.css.style(".ic-ts__field--focused", ...
    "border_color", "#22c55e", ...
    "box_shadow", "0 0 0 3px rgba(34, 197, 94, 0.15)");

% Leaf-shaped green tag pills
ts.css.style(".ic-tag", ...
    "background", "#dcfce7", ...
    "color", "#166534", ...
    "border_color", "#86efac", ...
    "border_radius", "9999px");

% Light cascade panels
ts.css.style(".ic-tp__panel", ...
    "background", "#f0fdf4", ...
    "border_color", "#bbf7d0");

ts.css.style(".ic-tp__row:hover", ...
    "background", "#dcfce7", ...
    "border_left", "3px solid #16a34a");

% Forest green checkboxes
ts.css.style(".ic-tp__check--on", ...
    "background", "#16a34a", ...
    "border_color", "#16a34a");