The m3e-tree component presents hierarchical data in a structure that users can navigate, with nested levels that open and collapse as needed.

import "@m3e/web/tree";

This section outlines usage examples and configuration guidance for the components in this package.

A basic tree consists of an m3e-tree component containing one or more m3e-tree-item. Items can be nested to create deeper levels in the hierarchy. Each item supplies its text through the label slot. Use the open attribute to control whether an item with nested children is expanded.

<m3e-tree>
  <m3e-tree-item open>
    <span slot="label">Getting Started</span>
    <m3e-tree-item>
      <span slot="label">Overview</span>
    </m3e-tree-item>
    <m3e-tree-item>
      <span slot="label">Installation</span>
    </m3e-tree-item>
  </m3e-tree-item>
  <!-- Additional items omitted for brevity -->
</m3e-tree>

Use the selected attribute to mark an item as selected. The change event fires when the user changes selection, and the selected property provides access to the currently selected item(s).

<m3e-tree>
  <m3e-tree-item open>
    <span slot="label">Getting Started</span>
    <m3e-tree-item selected>
      <span slot="label">Overview</span>
    </m3e-tree-item>
    <m3e-tree-item>
      <span slot="label">Installation</span>
    </m3e-tree-item>
  </m3e-tree-item>
  <!-- Additional items omitted for brevity -->
</m3e-tree>

Trees support both single-select and multi-select modes. Use the multi attribute of m3e-tree to allow multiple item to be selected simultaneously.

<m3e-tree multi>
  <m3e-tree-item>
    <span slot="label">Fruits</span>
    <m3e-tree-item>
      <span slot="label">Apples</span>
    </m3e-tree-item>
    <m3e-tree-item>
      <span slot="label">Oranges</span>
    </m3e-tree-item>
    <m3e-tree-item>
      <span slot="label">Bananas</span>
    </m3e-tree-item>
  </m3e-tree-item>
<!-- Additional items omitted for brevity -->
</m3e-tree>

Use the cascade attribute in conjunction with multi to enable cascade item selection.

<m3e-tree multi cascade>
  <m3e-tree-item>
    <span slot="label">Fruits</span>
    <m3e-tree-item>
      <span slot="label">Apples</span>
    </m3e-tree-item>
    <m3e-tree-item>
      <span slot="label">Oranges</span>
    </m3e-tree-item>
    <m3e-tree-item>
      <span slot="label">Bananas</span>
    </m3e-tree-item>
  </m3e-tree-item>
<!-- Additional items omitted for brevity -->
</m3e-tree>

Use the icon and selected-icon slots to present an icon for an item.

<m3e-tree>
  <m3e-tree-item open>
    <m3e-icon slot="icon" name="rocket_launch"></m3e-icon>
    <span slot="label">Getting Started</span>
    <m3e-tree-item>
      <m3e-icon slot="icon" name="near_me"></m3e-icon>
      <span slot="label">Overview</span>
    </m3e-tree-item>
    <m3e-tree-item>
      <m3e-icon slot="icon" name="package_2"></m3e-icon>
      <span slot="label">Installation</span>
    </m3e-tree-item>
  </m3e-tree-item>
</m3e-tree>

Use the toggle-icon and open-toggle-icon to change the icons used to expand and collapse an item.

<m3e-tree>
  <m3e-tree-item open>
    <m3e-icon slot="toggle-icon" name="add_box"></m3e-icon>
    <m3e-icon slot="open-toggle-icon" name="indeterminate_check_box"></m3e-icon>
    <span slot="label">Getting Started</span>
    <!-- Items omitted for brevity -->
  </m3e-tree-item>
</m3e-tree>

Trees are given ARIA role="tree", and items are assigned role="treeitem", indicating a structured, hierarchical navigation model that supports keyboard interaction, semantic grouping, and accessible labeling.

Expandable items use aria-expanded to indicate visibility of nested content. When selected, the item's selection state is reflected using aria-selected for single-select trees and aria-checked for multi-select trees.

Focus is managed on the m3e-tree container using tabindex="0", and the currently active item is referenced via aria-activedescendant, which points to the ID of the focused m3e-tree-item. This enables roving focus without shifting DOM focus, ensuring accessible keyboard navigation and consistent screen reader feedback.

Icons are given aria-hidden="true" ensure they're treated as purely decorative and excluded from the accessibility tree.

Disabling an item sets aria-disabled="true" signaling to assistive technologies that the item is not interactive.

The @m3e/web package uses JavaScript Modules. To use it directly in a browser without a bundler, use a module script similar to the following.

<script type="module" src="/node_modules/@m3e/web/dist/tree.js"></script>

In addition, you must use an import map to include additional dependencies.

<script type="importmap">
  {
    "imports": {
      "tslib": "https://cdn.jsdelivr.net/npm/tslib@2.8.1/+esm",
      "lit": "https://cdn.jsdelivr.net/npm/lit@3.3.0/+esm",
      "lit/": "https://cdn.jsdelivr.net/npm/lit@3.3.0/",
      "lit-html": "https://cdn.jsdelivr.net/npm/lit-html@3.3.0/+esm",
      "lit-html/directive.js": "https://cdn.jsdelivr.net/npm/lit-html@3.3.0/directive.js",
      "lit-html/directives/if-defined.js": "https://cdn.jsdelivr.net/npm/lit-html@3.3.0/directives/if-defined.js",
      "@lit/reactive-element": "https://cdn.jsdelivr.net/npm/@lit/reactive-element@2.0.4/+esm",
      "@lit/reactive-element/": "https://cdn.jsdelivr.net/npm/@lit/reactive-element@2.0.4/",
      "@m3e/web/core": "/node_modules/@m3e/web/dist/core.js",
      "@m3e/web/core/a11y": "/node_modules/@m3e/web/dist/core-a11y.js",
      "@m3e/web/core/bidi": "/node_modules/@m3e/web/dist/core-bidi.js"
    }
  }
</script>

For production builds, use the minified files to ensure optimal load performance.

The @m3e/web package includes a Custom Elements Manifest (custom-elements.json), which documents the properties, attributes, slots, events and CSS custom properties of each component.

You can explore the API below, or integrate the manifest into your own tooling.