Since Shoelace 2.0 Code stable

Tree

sl-tree

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.

Examples

Basic Tree

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

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

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

sl-tree
  sl-tree-item
    | Deciduous
    sl-tree-item Birch
    sl-tree-item
      | Maple
      sl-tree-item Field maple
      sl-tree-item Red maple
      sl-tree-item Sugar maple
    sl-tree-item Oak
  sl-tree-item
    | Coniferous
    sl-tree-item Cedar
    sl-tree-item Pine
    sl-tree-item Spruce
  sl-tree-item
    | Non-trees
    sl-tree-item Bamboo
    sl-tree-item Cactus
    sl-tree-item Fern

Selection Modes

The selection attribute lets you change the selection behavior of the tree.

  • Use single to allow the selection of a single item (default).
  • Use multiple to allow the selection of multiple items.
  • Use leaf to only allow leaf nodes to be selected.
Single Multiple Leaf
Item 1 Item A Item Z Item Y Item X Item B Item C Item 2 Item 3 
<sl-select id="selection-mode" value="single" label="Selection">
  <sl-option value="single">Single</sl-option>
  <sl-option value="multiple">Multiple</sl-option>
  <sl-option value="leaf">Leaf</sl-option>
</sl-select>

<br />

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

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

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

sl-select#selection-mode value="single" label="Selection"
  sl-option value="single" Single
  sl-option value="multiple" Multiple
  sl-option value="leaf" Leaf
br
sl-tree.tree-selectable
  sl-tree-item
    | Item 1
    sl-tree-item
      | Item A
      sl-tree-item Item Z
      sl-tree-item Item Y
      sl-tree-item Item X
    sl-tree-item Item B
    sl-tree-item Item C
  sl-tree-item Item 2
  sl-tree-item Item 3

javascript:
  const selectionMode = document.querySelector(#selection-mode);
  const tree = document.querySelector(.tree-selectable);

  selectionMode.addEventListener(sl-change, () => {
    tree.querySelectorAll(sl-tree-item).forEach(item => (item.selected = false));
    tree.selection = selectionMode.value;
  });

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 
<sl-tree class="tree-with-lines">
  <sl-tree-item expanded>
    Deciduous
    <sl-tree-item>Birch</sl-tree-item>
    <sl-tree-item expanded>
      Maple
      <sl-tree-item>Field maple</sl-tree-item>
      <sl-tree-item>Red maple</sl-tree-item>
      <sl-tree-item>Sugar maple</sl-tree-item>
    </sl-tree-item>
    <sl-tree-item>Oak</sl-tree-item>
  </sl-tree-item>

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

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

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

sl-tree.tree-with-lines
  sl-tree-item expanded=true
    | Deciduous
    sl-tree-item Birch
    sl-tree-item expanded=true
      | Maple
      sl-tree-item Field maple
      sl-tree-item Red maple
      sl-tree-item Sugar maple
    sl-tree-item Oak
  sl-tree-item
    | Coniferous
    sl-tree-item Cedar
    sl-tree-item Pine
    sl-tree-item Spruce
  sl-tree-item
    | Non-trees
    sl-tree-item Bamboo
    sl-tree-item Cactus
    sl-tree-item Fern

css:
  .tree-with-lines {
    --indent-guide-width: 1px;
  }

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 sl-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 
<sl-tree>
  <sl-tree-item lazy>Available Trees</sl-tree-item>
</sl-tree>

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

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

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

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

sl-tree
  sl-tree-item lazy=true Available Trees

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

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

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

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

Customizing the Expand and Collapse Icons

Use the expand-icon and collapse-icon slots to change the expand and collapse 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 
<sl-tree class="custom-icons">
  <sl-icon name="plus" slot="expand-icon"></sl-icon>
  <sl-icon name="minus" slot="collapse-icon"></sl-icon>

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

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

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

<style>
  .custom-icons sl-tree-item::part(expand-button) {
    /* Disable the expand/collapse animation */
    rotate: none;
  }
</style>

sl-tree.custom-icons
  sl-icon name="plus" slot="expand-icon"
  sl-icon name="minus" slot="collapse-icon"
  sl-tree-item
    | Deciduous
    sl-tree-item Birch
    sl-tree-item
      | Maple
      sl-tree-item Field maple
      sl-tree-item Red maple
      sl-tree-item Sugar maple
    sl-tree-item Oak
  sl-tree-item
    | Coniferous
    sl-tree-item Cedar
    sl-tree-item Pine
    sl-tree-item Spruce
  sl-tree-item
    | Non-trees
    sl-tree-item Bamboo
    sl-tree-item Cactus
    sl-tree-item Fern

css:
  .custom-icons sl-tree-item::part(expand-button) {
    /* Disable the expand/collapse animation */
    rotate: none;
  }

With Icons

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

Documents Photos birds.jpg kitten.jpg puppy.jpg Writing draft.txt final.pdf sales.xls 
<sl-tree class="tree-with-icons">
  <sl-tree-item expanded>
    <sl-icon name="folder"></sl-icon>
    Documents

    <sl-tree-item>
      <sl-icon name="folder"> </sl-icon>
      Photos
      <sl-tree-item>
        <sl-icon name="photo"></sl-icon>
        birds.jpg
      </sl-tree-item>
      <sl-tree-item>
        <sl-icon name="photo"></sl-icon>
        kitten.jpg
      </sl-tree-item>
      <sl-tree-item>
        <sl-icon name="photo"></sl-icon>
        puppy.jpg
      </sl-tree-item>
    </sl-tree-item>

    <sl-tree-item>
      <sl-icon name="folder"></sl-icon>
      Writing
      <sl-tree-item>
        <sl-icon name="document-text"></sl-icon>
        draft.txt
      </sl-tree-item>
      <sl-tree-item>
        <sl-icon name="document-arrow-down"></sl-icon>
        final.pdf
      </sl-tree-item>
      <sl-tree-item>
        <sl-icon name="document-chart-bar"></sl-icon>
        sales.xls
      </sl-tree-item>
    </sl-tree-item>
  </sl-tree-item>
</sl-tree>

sl-tree.tree-with-icons
  sl-tree-item expanded=true
    sl-icon name="folder"
    | Documents
    sl-tree-item
      sl-icon name="folder"
      | Photos
      sl-tree-item
        sl-icon name="photo"
        | birds.jpg
      sl-tree-item
        sl-icon name="photo"
        | kitten.jpg
      sl-tree-item
        sl-icon name="photo"
        | puppy.jpg
    sl-tree-item
      sl-icon name="folder"
      | Writing
      sl-tree-item
        sl-icon name="document-text"
        | draft.txt
      sl-tree-item
        sl-icon name="document-arrow-down"
        | final.pdf
      sl-tree-item
        sl-icon name="document-chart-bar"
        | sales.xls

Component Props

Property Default Details
selection 'single'

'single' | 'multiple' | 'leaf'

The selection behavior of the tree. Single selection allows only one node to be selected at a time. Multiple displays checkboxes and allows more than one node to be selected. Leaf allows only leaf nodes to be selected.

updateComplete A read-only promise that resolves when the component has finished updating.

Learn more about attributes and properties.

Slots

Name Details
(default) The default slot.
expand-icon The icon to show when the tree item is expanded. Works best with <sl-icon>.
collapse-icon The icon to show when the tree item is collapsed. Works best with <sl-icon>.

Learn more about using slots.

Events

Name Name Name React Event Details
sl-selection-change sl-selection-change sl-selection-change onSlSelectionChange

{ selection: SlTreeItem[] }

Emitted when a tree item is selected or deselected.

Learn more about events.

Custom Properties

Name Details
--indent-size

var(–sl-spacing-medium)

The size of the indentation for nested items.
--indent-guide-color

var(–sl-color-neutral-200)

The color of the indentation line.
--indent-guide-offset

0

The amount of vertical spacing to leave between the top and bottom of the indentation line’s starting position.

--indent-guide-style

solid

The style of the indentation line, e.g. solid, dotted, dashed.
--indent-guide-width

0

The width of the indentation line.

Learn more about customizing CSS custom properties.

CSS Parts

Name Description
base The component’s base wrapper.

Learn more about customizing CSS parts.