Default Gray Amethyst

Tree

<mo-tree> | MOTree
Since 1.2 stable

Trees allow you to display a hierarchical list of selectable tree items. Items with children can be expanded and collapsed as desired by the user.

Deciduous Birch Maple Field maple Red maple Sugar maple Oak Coniferous Cedar Pine Spruce Non-trees Bamboo Cactus Fern 
<mo-tree>
  <mo-tree-item>
    Deciduous
    <mo-tree-item>Birch</mo-tree-item>
    <mo-tree-item>
      Maple
      <mo-tree-item>Field maple</mo-tree-item>
      <mo-tree-item>Red maple</mo-tree-item>
      <mo-tree-item>Sugar maple</mo-tree-item>
    </mo-tree-item>
    <mo-tree-item>Oak</mo-tree-item>
  </mo-tree-item>

  <mo-tree-item>
    Coniferous
    <mo-tree-item>Cedar</mo-tree-item>
    <mo-tree-item>Pine</mo-tree-item>
    <mo-tree-item>Spruce</mo-tree-item>
  </mo-tree-item>

  <mo-tree-item>
    Non-trees
    <mo-tree-item>Bamboo</mo-tree-item>
    <mo-tree-item>Cactus</mo-tree-item>
    <mo-tree-item>Fern</mo-tree-item>
  </mo-tree-item>
</mo-tree>

import { MOTree, MOTreeItem } from '@modes-web-components/dist/react';

const App = () => (
  <MOTree>
    <MOTreeItem>
      Deciduous
      <MOTreeItem>Birch</MOTreeItem>
      <MOTreeItem>
        Maple
        <MOTreeItem>Field maple</MOTreeItem>
        <MOTreeItem>Red maple</MOTreeItem>
        <MOTreeItem>Sugar maple</MOTreeItem>
      </MOTreeItem>
      <MOTreeItem>Oak</MOTreeItem>
    </MOTreeItem>

    <MOTreeItem>
      Coniferous
      <MOTreeItem>Cedar</MOTreeItem>
      <MOTreeItem>Pine</MOTreeItem>
      <MOTreeItem>Spruce</MOTreeItem>
    </MOTreeItem>

    <MOTreeItem>
      Non-trees
      <MOTreeItem>Bamboo</MOTreeItem>
      <MOTreeItem>Cactus</MOTreeItem>
      <MOTreeItem>Fern</MOTreeItem>
    </MOTreeItem>
  </MOTree>
);

Examples

Selection modes

Use the selection attribute to change the selection behavior of the tree.

  • Set single to allow the selection of a single item (default).
  • Set multiple to allow the selection of multiple items.
  • Set leaf to allow the selection of a single leaf node. Clicking on a parent node will expand/collapse the node.
Single Multiple Leaf
Item 1 Item A Item Z Item Y Item X Item B Item C Item 2 Item 3 
<mo-select id="selection-mode" value="single" label="Selection">
  <mo-option value="single">Single</mo-option>
  <mo-option value="multiple">Multiple</mo-option>
  <mo-option value="leaf">Leaf</mo-option>
</mo-select>

<br />

<mo-tree class="tree-selectable">
  <mo-tree-item>
    Item 1
    <mo-tree-item>
      Item A
      <mo-tree-item>Item Z</mo-tree-item>
      <mo-tree-item>Item Y</mo-tree-item>
      <mo-tree-item>Item X</mo-tree-item>
    </mo-tree-item>
    <mo-tree-item>Item B</mo-tree-item>
    <mo-tree-item>Item C</mo-tree-item>
  </mo-tree-item>
  <mo-tree-item>Item 2</mo-tree-item>
  <mo-tree-item>Item 3</mo-tree-item>
</mo-tree>

<script>
  const selectionMode = document.querySelector('#selection-mode');
  const tree = document.querySelector('.tree-selectable');

  selectionMode.addEventListener('mo-change', () => {
    tree.querySelectorAll('mo-tree-item').forEach(item => (item.selected = false));
    tree.selection = selectionMode.value;
  });
</script>

import { MOTree, MOTreeItem } from '@modes-web-components/dist/react';

const App = () => {
  const [selection, setSelection] = useState('single');

  return (
    <>
      <MOSelect label="Selection" value={value} onMoChange={event => setSelection(event.target.value)}>
        <MOOption value="single">single</MOOption>
        <MOOption value="multiple">multiple</MOOption>
        <MOOption value="leaf">leaf</MOOption>
      </MOSelect>

      <br />

      <MOTree class="tree-selectable">
        <MOTreeItem>
          Item 1
          <MOTreeItem>
            Item A
            <MOTreeItem>Item Z</MOTreeItem>
            <MOTreeItem>Item Y</MOTreeItem>
            <MOTreeItem>Item X</MOTreeItem>
          </MOTreeItem>
          <MOTreeItem>Item B</MOTreeItem>
          <MOTreeItem>Item C</MOTreeItem>
        </MOTreeItem>
        <MOTreeItem>Item 2</MOTreeItem>
        <MOTreeItem>Item 3</MOTreeItem>
      </MOTree>
    </>
  );
};

Showing indent guides

Indent guides can be drawn by setting --indent-guide-width. You can also change the color, offset, and style, using --indent-guide-color, --indent-guide-style, and --indent-guide-offset, respectively.

Deciduous Birch Maple Field maple Red maple Sugar maple Oak Coniferous Cedar Pine Spruce Non-trees Bamboo Cactus Fern 
<mo-tree class="tree-with-lines">
  <mo-tree-item expanded>
    Deciduous
    <mo-tree-item>Birch</mo-tree-item>
    <mo-tree-item expanded>
      Maple
      <mo-tree-item>Field maple</mo-tree-item>
      <mo-tree-item>Red maple</mo-tree-item>
      <mo-tree-item>Sugar maple</mo-tree-item>
    </mo-tree-item>
    <mo-tree-item>Oak</mo-tree-item>
  </mo-tree-item>

  <mo-tree-item>
    Coniferous
    <mo-tree-item>Cedar</mo-tree-item>
    <mo-tree-item>Pine</mo-tree-item>
    <mo-tree-item>Spruce</mo-tree-item>
  </mo-tree-item>

  <mo-tree-item>
    Non-trees
    <mo-tree-item>Bamboo</mo-tree-item>
    <mo-tree-item>Cactus</mo-tree-item>
    <mo-tree-item>Fern</mo-tree-item>
  </mo-tree-item>
</mo-tree>

<style>
  .tree-with-lines {
    --indent-guide-width: 1px;
  }
</style>

import { MOTree, MOTreeItem } from '@modes-web-components/dist/react';

const App = () => (
  <MOTree class="tree-with-lines" style={{ '--indent-guide-width': '1px' }}>
    <MOTreeItem expanded>
      Deciduous
      <MOTreeItem>Birch</MOTreeItem>
      <MOTreeItem expanded>
        Maple
        <MOTreeItem>Field maple</MOTreeItem>
        <MOTreeItem>Red maple</MOTreeItem>
        <MOTreeItem>Sugar maple</MOTreeItem>
      </MOTreeItem>
      <MOTreeItem>Oak</MOTreeItem>
    </MOTreeItem>

    <MOTreeItem>
      Coniferous
      <MOTreeItem>Cedar</MOTreeItem>
      <MOTreeItem>Pine</MOTreeItem>
      <MOTreeItem>Spruce</MOTreeItem>
    </MOTreeItem>

    <MOTreeItem>
      Non-trees
      <MOTreeItem>Bamboo</MOTreeItem>
      <MOTreeItem>Cactus</MOTreeItem>
      <MOTreeItem>Fern</MOTreeItem>
    </MOTreeItem>
  </MOTree>
);

Lazy loading

Use the lazy attribute on a tree item to indicate that the content is not yet present and will be loaded later. When the user tries to expand the node, the loading state is set to true and the mo-lazy-load event will be emitted to allow you to load data asynchronously. The item will remain in a loading state until its content is changed.

If you want to disable this behavior after the first load, simply remove the lazy attribute and, on the next expand, the existing content will be shown instead.

Available Trees 
<mo-tree selection="leaf">
  <mo-tree-item lazy>Available Trees</mo-tree-item>
</mo-tree>

<script type="module">
  const lazyItem = document.querySelector('mo-tree-item[lazy]');

  lazyItem.addEventListener('mo-lazy-load', () => {
    // Simulate asynchronous loading
    setTimeout(() => {
      const subItems = ['Birch', 'Cedar', 'Maple', 'Pine'];

      for (const item of subItems) {
        const treeItem = document.createElement('mo-tree-item');
        treeItem.innerText = item;
        lazyItem.append(treeItem);
      }

      // Disable lazy mode once the content has been loaded
      lazyItem.lazy = false;
    }, 1000);
  });
</script>

import { MOTree, MOTreeItem } from '@modes-web-components/dist/react';

const App = () => {
  const [childItems, setChildItems] = useState([]);
  const [lazy, setLazy] = useState(true);

  const handleLazyLoad = () => {
    // Simulate asynchronous loading
    setTimeout(() => {
      setChildItems(['Birch', 'Cedar', 'Maple', 'Pine']);

      // Disable lazy mode once the content has been loaded
      setLazy(false);
    }, 1000);
  };

  return (
    <MOTree selection="leaf">
      <MOTreeItem lazy={lazy} onMOLazyLoad={handleLazyLoad}>
        Available Trees
        {childItems.map(item => (
          <MOTreeItem>{item}</MOTreeItem>
        ))}
      </MOTreeItem>
    </MOTree>
  );
};

Custom expanded/collapsed icons

Use the expanded-icon or collapsed-icon slots to change the expanded and collapsed tree element icons respectively. To disable the animation, override the rotate property on the expand-button part as shown below.

Deciduous Birch Maple Field maple Red maple Sugar maple Oak Coniferous Cedar Pine Spruce Non-trees Bamboo Cactus Fern 
<mo-tree class="custom-icons" selection="leaf">
  <mo-icon name="plus" slot="collapsed-icon"></mo-icon>
  <mo-icon name="minus" slot="expanded-icon"></mo-icon>

  <mo-tree-item>
    Deciduous
    <mo-tree-item>Birch</mo-tree-item>
    <mo-tree-item>
      Maple
      <mo-tree-item>Field maple</mo-tree-item>
      <mo-tree-item>Red maple</mo-tree-item>
      <mo-tree-item>Sugar maple</mo-tree-item>
    </mo-tree-item>
    <mo-tree-item>Oak</mo-tree-item>
  </mo-tree-item>

  <mo-tree-item>
    Coniferous
    <mo-tree-item>Cedar</mo-tree-item>
    <mo-tree-item>Pine</mo-tree-item>
    <mo-tree-item>Spruce</mo-tree-item>
  </mo-tree-item>

  <mo-tree-item>
    Non-trees
    <mo-tree-item>Bamboo</mo-tree-item>
    <mo-tree-item>Cactus</mo-tree-item>
    <mo-tree-item>Fern</mo-tree-item>
  </mo-tree-item>
</mo-tree>
<style>
  .custom-icons mo-tree-item::part(expand-button) {
    /* Disable the expand/collapse animation */
    rotate: none;
  }
</style>

import { MOTree, MOTreeItem } from '@modes-web-components/dist/react';

const App = () => (
  <MOTree>
    <MOIcon name="plus" slot="collapsed-icon"></MOIcon>
    <MOIcon name="minus" slot="expanded-icon"></MOIcon>

    <MOTreeItem>
      Deciduous
      <MOTreeItem>Birch</MOTreeItem>
      <MOTreeItem>
        Maple
        <MOTreeItem>Field maple</MOTreeItem>
        <MOTreeItem>Red maple</MOTreeItem>
        <MOTreeItem>Sugar maple</MOTreeItem>
      </MOTreeItem>
      <MOTreeItem>Oak</MOTreeItem>
    </MOTreeItem>

    <MOTreeItem>
      Coniferous
      <MOTreeItem>Cedar</MOTreeItem>
      <MOTreeItem>Pine</MOTreeItem>
      <MOTreeItem>Spruce</MOTreeItem>
    </MOTreeItem>

    <MOTreeItem>
      Non-trees
      <MOTreeItem>Bamboo</MOTreeItem>
      <MOTreeItem>Cactus</MOTreeItem>
      <MOTreeItem>Fern</MOTreeItem>
    </MOTreeItem>
  </MOTree>
);

With icons

Decorative icons can be used before labels to provide hints for each node.

Root Folder 1 File 1 – 1 File 1 – 2 File 1 – 3 Folder 2 File 2 – 1 File 2 – 2 File 1 
<mo-tree class="tree-with-icons">
  <mo-tree-item expanded>
    <mo-icon name="equipment"></mo-icon>
    Root

    <mo-tree-item>
      <mo-icon name="equipment"> </mo-icon>
      Folder 1
      <mo-tree-item>
        <mo-icon name="document"></mo-icon>
        File 1 - 1
      </mo-tree-item>
      <mo-tree-item disabled>
        <mo-icon name="document"></mo-icon>
        File 1 - 2
      </mo-tree-item>
      <mo-tree-item>
        <mo-icon name="document"></mo-icon>
        File 1 - 3
      </mo-tree-item>
    </mo-tree-item>

    <mo-tree-item>
      <mo-icon name="equipment"></mo-icon>
      Folder 2
      <mo-tree-item>
        <mo-icon name="document"></mo-icon>
        File 2 - 1
      </mo-tree-item>
      <mo-tree-item>
        <mo-icon name="document"></mo-icon>
        File 2 - 2
      </mo-tree-item>
    </mo-tree-item>
    <mo-tree-item>
      <mo-icon name="document"></mo-icon>
      File 1
    </mo-tree-item>
  </mo-tree-item>
</mo-tree>

import { MOIcon, MOTree, MOTreeItem } from '@modes-web-components/dist/react';

const App = () => {
  return (
    <MOTree class="tree-with-icons">
      <MOTreeItem expanded>
        <MOIcon name="equipment" />
        Root
        <MOTreeItem>
          <MOIcon name="equipment" />
          Folder 1<MOTreeItem>
            <MOIcon name="document" />
            File 1 - 1
          </MOTreeItem>
          <MOTreeItem disabled>
            <MOIcon name="document" />
            File 1 - 2
          </MOTreeItem>
          <MOTreeItem>
            <MOIcon name="document" />
            File 1 - 3
          </MOTreeItem>
        </MOTreeItem>
        <MOTreeItem>
          <MOIcon name="document" />
          Folder 2<MOTreeItem>
            <MOIcon name="document" />
            File 2 - 1
          </MOTreeItem>
          <MOTreeItem>
            <MOIcon name="document" />
            File 2 - 2
          </MOTreeItem>
        </MOTreeItem>
        <MOTreeItem>
          <MOIcon name="document" />
          File 1
        </MOTreeItem>
      </MOTreeItem>
    </MOTree>
  );
};

Importing

If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.

Bundler React Script

To import this component using a bundler:

import '@metsooutotec/modes-web-components/dist/components/tree/tree.js';

To import this component as a React component:

import MOTree from '@metsooutotec/modes-web-components/dist/react/tree/';

To import this component using a script tag:

<script type="module" src="https://modes-web.metso.com/dist/components/cdn/components/tree/tree.js"></script>

Slots

Name Description
(default) The default slot.
expanded-icon The icon to show when the tree item is expanded.
collapsed-icon The icon to show when the tree item is collapsed.

Learn more about using slots.

Properties

Name Description Reflects Type Default
selection Specifies the selection behavior of the Tree 'single' | 'multiple' | 'leaf' 'single'
updateComplete A read-only promise that resolves when the component has finished updating.

Learn more about attributes and properties.

Events

Name React Event Description Event Detail
mo-selection-change onMoSelectionChange Emitted when an item gets selected or deselected { selection: this.selectedItems }

Learn more about events.

Custom Properties

Name Description Default
--indent-size The size of the indentation for nested items. var(–mo-spacing-medium)
--indent-guide-color The color of the indentation line. var(–mo-color-neutral-200)
--indent-guide-offset The amount of vertical spacing to leave between the top and bottom of the indentation line’s starting position. 0
--indent-guide-style The style of the indentation line, e.g. solid, dotted, dashed. solid
--indent-guide-width The width of the indentation line. 0

Learn more about customizing CSS custom properties.

Parts

Name Description
base The component’s internal wrapper.

Learn more about customizing CSS parts.