Correct and idiomatic ways to use the <mds-tree-item> component, ordered from most common to most specialized. Patterns assume a working knowledge of the compound parent <mds-tree> and the shared component rules in agents/conventions.md.

Basic Node Inside a Tree

The minimal form: a labeled item nested inside its parent <mds-tree>. The tree orchestrates toggle, truncate, and actions for all descendants, so you rarely need to set them per item.

<mds-tree>
  <mds-tree-item label="Documenti"></mds-tree-item>
  <mds-tree-item label="Immagini"></mds-tree-item>
  <mds-tree-item label="Video"></mds-tree-item>
</mds-tree>

Nested Hierarchy

Place <mds-tree-item> elements in the default slot of another <mds-tree-item> to build a hierarchy. The component detects nested children automatically and renders the branch connector.

<mds-tree>
  <mds-tree-item label="Ufficio Tecnico">
    <mds-tree-item label="Pratiche edilizie">
      <mds-tree-item label="Domanda 2024-001"></mds-tree-item>
      <mds-tree-item label="Domanda 2024-002"></mds-tree-item>
    </mds-tree-item>
    <mds-tree-item label="Concessioni"></mds-tree-item>
  </mds-tree-item>
  <mds-tree-item label="Ragioneria"></mds-tree-item>
</mds-tree>

Pre-Opened Node

Set expanded to open a node on first render. Useful for landing pages where a specific branch should already be visible.

<mds-tree>
  <mds-tree-item label="Pratiche in corso" expanded>
    <mds-tree-item label="Richiesta #1042"></mds-tree-item>
    <mds-tree-item label="Richiesta #1043"></mds-tree-item>
  </mds-tree-item>
  <mds-tree-item label="Archivio"></mds-tree-item>
</mds-tree>

Node with a Leading Icon

Use the icon prop to add an icon before the label text. Reference icons by their slug - no .svg extension. The icon is independent of the toggle affordance.

<mds-tree>
  <mds-tree-item label="Segreteria" icon="mi/baseline/desk">
    <mds-tree-item label="Genoveffo Baci" icon="mi/baseline/person"></mds-tree-item>
    <mds-tree-item label="Donaldo Trombetta" icon="mi/baseline/person"></mds-tree-item>
  </mds-tree-item>
  <mds-tree-item label="Archivio" icon="mi/baseline/archive"></mds-tree-item>
</mds-tree>

Folder Toggle Style

When the tree uses toggle="folder", each item swaps between a closed-folder and open-folder icon as it expands. Set toggle on the parent <mds-tree> and all items inherit it automatically: the tree writes its own value (default chevron) onto every item when it loads, so a toggle set on a single item is overwritten.

<mds-tree toggle="folder">
  <mds-tree-item label="Modulistica">
    <mds-tree-item label="Modulo A"></mds-tree-item>
    <mds-tree-item label="Modulo B"></mds-tree-item>
  </mds-tree-item>
</mds-tree>

Per-Item Action Controls

Slot <mds-button> or <mds-icon> elements into the action slot to attach contextual controls to a node. Use the actions prop (inherited from the tree) to choose when they appear: "auto" shows them on hover, "visible" keeps them always visible.

<mds-tree actions="auto">
  <mds-tree-item label="Contratto 2024">
    <mds-button
      slot="action"
      icon="mi/baseline/attach-file"
      variant="primary"
      tone="text"
      title="Allega documento"
    ></mds-button>
    <mds-button
      slot="action"
      icon="mi/baseline/more-vert"
      variant="primary"
      tone="text"
      title="Altre opzioni"
    ></mds-button>
    <mds-tree-item label="Allegato 1"></mds-tree-item>
  </mds-tree-item>
</mds-tree>

Asynchronous (Lazy-Load) Node

Set async on a node when its children must be fetched on demand. On expand the item shows a spinner on its toggle and emits mdsTreeItemExpand; call expand() on the element once data is ready to finalize opening. The toggle (and so the spinner) shows only if the item already had child items at first render; children appended later do not add it. After resolving, set async to undefined (or remove the attribute) so subsequent toggles work synchronously.

<mds-tree>
  <mds-tree-item async label="Dipendenti" icon="mi/baseline/group" id="dept-node">
    <!-- children injected after fetch -->
  </mds-tree-item>
</mds-tree>

<script>
  document.getElementById('dept-node').addEventListener(
    'mdsTreeItemExpand',
    async (event) => {
      const node = event.detail.element;
      if (!node.async) return;
      const people = await fetchDepartmentPeople();
      people.forEach((name) => {
        const item = document.createElement('mds-tree-item');
        item.label = name;
        item.icon = 'mi/baseline/person';
        node.appendChild(item);
      });
      await node.expand();
      node.async = undefined;
    },
  );
</script>

Reacting to Expand and Collapse Events

Listen to mdsTreeItemExpand and mdsTreeItemCollapse to keep external state (e.g. a sidebar breadcrumb or a selection store) in sync. mdsTreeItemCollapse fires whenever an item closes; mdsTreeItemExpand fires only for items marked async, when they are asked to open. Both events carry { element } - the host <mds-tree-item> - so you can read its label or any other prop.

<mds-tree id="struttura-tree">
  <mds-tree-item label="Ufficio A">
    <mds-tree-item label="Sezione 1"></mds-tree-item>
  </mds-tree-item>
</mds-tree>

<script>
  // emitted only by items marked async
  document.getElementById('struttura-tree').addEventListener('mdsTreeItemExpand', (event) => {
    console.log('Espanso:', event.detail.element.label);
  });
  document.getElementById('struttura-tree').addEventListener('mdsTreeItemCollapse', (event) => {
    console.log('Compresso:', event.detail.element.label);
  });
</script>

Multi-Line Label with Clamping

Set truncate="all" on the tree (it overwrites the items’ own value) to allow multi-line text with clamping controlled by --mds-tree-item-line-clamp. Use this for long file paths or descriptive labels.

<mds-tree truncate="all">
  <mds-tree-item label="Delibera di Giunta Comunale n. 42 del 15 marzo 2024 - approvazione bilancio">
  </mds-tree-item>
  <mds-tree-item label="Verbale seduta straordinaria del Consiglio Comunale del 22 aprile 2024">
  </mds-tree-item>
</mds-tree>

CSS Customization

Customize the item’s appearance only through its documented --mds-tree-item-* CSS custom properties. Set them on the host or a parent selector; use the semantic color roles via rgb(var(--magma-<role>)) to stay compatible with dark mode and high-contrast.

.archivio-tree mds-tree-item {
  --mds-tree-item-branch-border-color: rgb(var(--magma-accent-border));
  --mds-tree-item-branch-dot-expanded-color: rgb(var(--magma-accent-fg));
  --mds-tree-item-label-hover-background: rgb(var(--magma-wash-base));
  --mds-tree-item-toggle-icon-chevron-default-color: rgb(var(--magma-accent-on-emphasis));
  --mds-tree-item-transition-duration: 200ms;
}

Styling the Actions Container via Shadow Parts

Use ::part(actions-container) and ::part(actions-list) to style the wrapper and inner list of action controls when the CSS custom properties are not sufficient. This is the documented exception - do not target other internal parts.

mds-tree-item::part(actions-container) {
  background: rgb(var(--magma-wash-soft));
  border-radius: var(--magma-radius-md);
}

mds-tree-item::part(actions-list) {
  gap: calc(var(--spacing) * 200);
}