Tree item<mds-tree-item>Generated from @maggioli-design-system/magma@2.3.0dist/documentation.json. Encapsulation: shadow.
The first example of the Pattern page, live. Change its props below and the preview follows; Reset brings the example back as it was.
Props
actionsenumShow actions on the tree item on hover or by default.
appearanceenumReflects the parent tree appearance (set by mds-tree); drives the depth/none layout without :host-context
toggleenumSpecifies the icon of the element
togglePositionenumReflects the parent tree toggle icon position (set by mds-tree); drives the toggle-icon layout without :host-context
truncateenumTruncate the text of the element on one single line.
asyncasyncbooleanSpecifies the tree should be opened asynchronously when after the click.
expandedexpandedbooleanSpecifies if the tree is expanded.
iconstringThe icon displayed in the button
labelstringSpecifies the label of the tree item
depthnumberSpecifies the tree branch depth. Internal: used by CSS to remove branch lines on first-level elements.
Overview
The <mds-tree-item> web component is the node primitive of the Magma Design System tree view: it represents a single labeled, expandable/collapsible entry inside an <mds-tree> and is also the recursive container for its own descendants. It replaces the role of an <li> within a nested disclosure list.
Semantic Behavior
Compound child only: It must be a direct slot child of <mds-tree> (first-level nodes) or of another <mds-tree-item> (nested nodes). It is not used standalone, and the default slot is reserved for further <mds-tree-item> children - not arbitrary content.Parent-driven defaults: The parent <mds-tree> writes toggle, togglePosition, appearance and truncate onto its descendant items when it loads (overwriting their own values), and expanded when its own value changes; actions is inherited from the nearest ancestor that sets it. These props are therefore orchestrated by the tree rather than set per-item. First-level items receive depth = 0.Self-managed expansion: Clicking the toggle or label flips expanded, swaps the toggle icon, and animates the children container; on collapse it emits mdsTreeItemCollapse.Asynchronous expansion: While async is set, an expand click does not open the node - it shows a spinner and emits mdsTreeItemExpand so the application can lazy-load children; the application then calls the public expand() method to finalize opening. Without async, opening emits no event.Bubbled events: mdsTreeItemExpand and mdsTreeItemCollapse both carry { element } (the host item) so the tree or application can react to node lifecycle.Leaf vs. branch: It detects whether it contains nested items (once, at first render) and whether it has slotted actions, adjusting the connector/branch rendering and actions visibility accordingly.Public method: expand() opens the node and clears the awaiting state (used to resolve async loads).
Properties & Visual Configurations
toggle: Picks the disclosure affordance - chevron (default arrow) or folder (closed/open folder icons that swap as the user opens and closes the node). Normally inherited from the parent tree for visual consistency.actions: Controls when slotted action controls appear - auto reveals them on hover, visible keeps them always shown. Place those controls in the named action slot.async: Enable when a node’s children are loaded on demand; pair it with a listener on mdsTreeItemExpand and a call to expand() once data is ready.expanded: Mutable open/closed state; set it directly to pre-open a node, but expect the parent tree to override it when the whole tree expands or collapses.truncate: Governs label overflow (word, all, none); all enables multi-line clamping. Usually inherited from the tree.icon: Optional leading icon rendered inside the label button, independent of the toggle affordance.depth: Internal/parent-assigned; drives branch-line decoration and should not normally be set by consumers.