Tree

<wa-tree>

Since 2.0

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.

                
    Parent Node
    Child Node 1
    
      Child Node 2
      Child Node 2 - 1
      Child Node 2 - 2

<wa-tree selection="multiple">
  <wa-tree-item>
    Parent Node
    <wa-tree-item selected>Child Node 1</wa-tree-item>
    <wa-tree-item>
      Child Node 2
      <wa-tree-item>Child Node 2 - 1</wa-tree-item>
      <wa-tree-item>Child Node 2 - 2</wa-tree-item>
    </wa-tree-item>
  </wa-tree-item>
</wa-tree>

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

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

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

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

Examples Jump to heading

Selection Modes Jump to heading

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

<wa-select id="selection-mode" value="single" label="Selection">
  <wa-option value="single">Single</wa-option>
  <wa-option value="multiple">Multiple</wa-option>
  <wa-option value="leaf">Leaf</wa-option>
</wa-select>

<br />

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

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

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

Showing Indent Guides Jump to heading

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

<wa-tree class="tree-with-lines">
  <wa-tree-item expanded>
    Deciduous
    <wa-tree-item>Birch</wa-tree-item>
    <wa-tree-item expanded>
      Maple
      <wa-tree-item>Field maple</wa-tree-item>
      <wa-tree-item>Red maple</wa-tree-item>
      <wa-tree-item>Sugar maple</wa-tree-item>
    </wa-tree-item>
    <wa-tree-item>Oak</wa-tree-item>
  </wa-tree-item>

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

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

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

Lazy Loading Jump to heading

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 wa-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

<wa-tree>
  <wa-tree-item lazy>Available Trees</wa-tree-item>
</wa-tree>

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

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

      for (const item of subItems) {
        const treeItem = document.createElement('wa-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 Jump to heading

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

<wa-tree class="custom-icons">
  <wa-icon name="square-plus" variant="solid" slot="expand-icon"></wa-icon>
  <wa-icon name="square-minus" variant="solid" slot="collapse-icon"></wa-icon>

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

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

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

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

With Icons Jump to heading

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

<wa-tree class="tree-with-icons">
  <wa-tree-item expanded>
    <wa-icon name="folder" variant="regular"></wa-icon>
    Documents

    <wa-tree-item>
      <wa-icon name="folder" variant="regular"> </wa-icon>
      Photos
      <wa-tree-item>
        <wa-icon name="image" variant="regular"></wa-icon>
        birds.jpg
      </wa-tree-item>
      <wa-tree-item>
        <wa-icon name="image" variant="regular"></wa-icon>
        kitten.jpg
      </wa-tree-item>
      <wa-tree-item>
        <wa-icon name="image" variant="regular"></wa-icon>
        puppy.jpg
      </wa-tree-item>
    </wa-tree-item>

    <wa-tree-item>
      <wa-icon name="folder" variant="regular"></wa-icon>
      Writing
      <wa-tree-item>
        <wa-icon name="file" variant="regular"></wa-icon>
        draft.txt
      </wa-tree-item>
      <wa-tree-item>
        <wa-icon name="file-pdf" variant="regular"></wa-icon>
        final.pdf
      </wa-tree-item>
      <wa-tree-item>
        <wa-icon name="file-lines" variant="regular"></wa-icon>
        sales.xls
      </wa-tree-item>
    </wa-tree-item>
  </wa-tree-item>
</wa-tree>

Slots Jump to heading

Learn more about using slots.

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

Attributes & Properties Jump to heading

Learn more about attributes and properties.

Name	Description	Reflects
`selection` `selection`	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. Type `'single' \| 'multiple' \| 'leaf'` Default `'single'`

Events Jump to heading

Learn more about events.

Name	Description
`wa-selection-change`	Emitted when a tree item is selected or deselected.

CSS custom properties Jump to heading

Learn more about CSS custom properties.

Name	Description
`--indent-size`	The size of the indentation for nested items. Default `var(--wa-space-m)`
`--indent-guide-color`	The color of the indentation line. Default `var(--wa-color-surface-border)`
`--indent-guide-offset`	The amount of vertical spacing to leave between the top and bottom of the indentation line's starting position. Default `0`
`--indent-guide-style`	The style of the indentation line, e.g. solid, dotted, dashed. Default `solid`
`--indent-guide-width`	The width of the indentation line. Default `0`

CSS parts Jump to heading

Learn more about CSS parts.

Name	Description	CSS selector
`base`	The component's base wrapper.	`::part(base)`

Dependencies Jump to heading

This component automatically imports the following elements. Sub-dependencies, if any exist, will also be included in this list.

Importing Jump to heading

Autoloading components via projects is the recommended way to import components. If you prefer to do it manually, use one of the following code snippets.

CDN

npm

React

Let your project code do the work! Sign up for free to use a project with your very own CDN — it's the fastest and easiest way to use Web Awesome.

To manually import this component from NPM, use the following code.

import '@awesome.me/webawesome/dist/components/tree/tree.js';

To manually import this component from React, use the following code.

import WaTree from '@awesome.me/webawesome/dist/react/tree';

Need a hand?

Report a bug

Ask for help

Getting Started

Resources

Components

Style Utilities

Layout

Patterns

Theming

Design Tokens

Terms & Policies

Web Awesome

Tree

Examples Jump to heading

Selection Modes Jump to heading

Showing Indent Guides Jump to heading

Lazy Loading Jump to heading

Customizing the Expand and Collapse Icons Jump to heading

With Icons Jump to heading

Slots Jump to heading

Attributes & Properties Jump to heading

Events Jump to heading

CSS custom properties Jump to heading

CSS parts Jump to heading

Dependencies Jump to heading

Importing Jump to heading

Get a lifetime discount on Web Awesome Pro!

Getting Started

Resources

Components

Style Utilities

Layout

Patterns

Theming

Design Tokens

Terms & Policies

Web Awesome

Web Awesome Elsewhere

Tree

Examples Jump to heading

Selection Modes Jump to heading

Showing Indent Guides Jump to heading

Lazy Loading Jump to heading

Customizing the Expand and Collapse Icons Jump to heading

With Icons Jump to heading

Slots Jump to heading

Attributes & Properties Jump to heading

Events Jump to heading

CSS custom properties Jump to heading

CSS parts Jump to heading

Dependencies Jump to heading

Importing Jump to heading

Get a lifetime discount on Web Awesome Pro!