Light Dark System
Get ready for more awesome! Web Awesome, the next iteration of Shoelace, is on Kickstarter. Read Our Story

Tree Item

<sl-tree-item> | SlTreeItem
Since 2.0 stable

A tree item serves as a hierarchical node that lives inside a tree.

Item 1 Item A Item B Item C Item 2 Item 3 
<sl-tree>
  <sl-tree-item>
    Item 1
    <sl-tree-item>Item A</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>

import SlTree from '@shoelace-style/shoelace/dist/react/tree';
import SlTreeItem from '@shoelace-style/shoelace/dist/react/tree-item';

const App = () => (
  <SlTree>
    <SlTreeItem>
      Item 1
      <SlTreeItem>Item A</SlTreeItem>
      <SlTreeItem>Item B</SlTreeItem>
      <SlTreeItem>Item C</SlTreeItem>
    </SlTreeItem>
    <SlTreeItem>Item 2</SlTreeItem>
    <SlTreeItem>Item 3</SlTreeItem>
  </SlTree>
);

Examples

Nested tree items

A tree item can contain other tree items. This allows the node to be expanded or collapsed by the user.

Item 1 Item A Item Z Item Y Item X Item B Item C Item 2 Item 3 
<sl-tree>
  <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>

import SlTree from '@shoelace-style/shoelace/dist/react/tree';
import SlTreeItem from '@shoelace-style/shoelace/dist/react/tree-item';

const App = () => (
  <SlTree>
    <SlTreeItem>
      Item 1
      <SlTreeItem>
        Item A
        <SlTreeItem>Item Z</SlTreeItem>
        <SlTreeItem>Item Y</SlTreeItem>
        <SlTreeItem>Item X</SlTreeItem>
      </SlTreeItem>
      <SlTreeItem>Item B</SlTreeItem>
      <SlTreeItem>Item C</SlTreeItem>
    </SlTreeItem>
    <SlTreeItem>Item 2</SlTreeItem>
    <SlTreeItem>Item 3</SlTreeItem>
  </SlTree>
);

Selected

Use the selected attribute to select a tree item initially.

Item 1 Item A Item B Item C Item 2 Item 3 
<sl-tree>
  <sl-tree-item selected>
    Item 1
    <sl-tree-item>Item A</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>

import SlTree from '@shoelace-style/shoelace/dist/react/tree';
import SlTreeItem from '@shoelace-style/shoelace/dist/react/tree-item';

const App = () => (
  <SlTree>
    <SlTreeItem selected>
      Item 1
      <SlTreeItem>Item A</SlTreeItem>
      <SlTreeItem>Item B</SlTreeItem>
      <SlTreeItem>Item C</SlTreeItem>
    </SlTreeItem>
    <SlTreeItem>Item 2</SlTreeItem>
    <SlTreeItem>Item 3</SlTreeItem>
  </SlTree>
);

Expanded

Use the expanded attribute to expand a tree item initially.

Item 1 Item A Item Z Item Y Item X Item B Item C Item 2 Item 3 
<sl-tree>
  <sl-tree-item expanded>
    Item 1
    <sl-tree-item expanded>
      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>

import SlTree from '@shoelace-style/shoelace/dist/react/tree';
import SlTreeItem from '@shoelace-style/shoelace/dist/react/tree-item';

const App = () => (
  <SlTree>
    <SlTreeItem expanded>
      Item 1
      <SlTreeItem expanded>
        Item A
        <SlTreeItem>Item Z</SlTreeItem>
        <SlTreeItem>Item Y</SlTreeItem>
        <SlTreeItem>Item X</SlTreeItem>
      </SlTreeItem>
      <SlTreeItem>Item B</SlTreeItem>
      <SlTreeItem>Item C</SlTreeItem>
    </SlTreeItem>
    <SlTreeItem>Item 2</SlTreeItem>
    <SlTreeItem>Item 3</SlTreeItem>
  </SlTree>
);

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.

Script Import Bundler React

To import this component from the CDN using a script tag: 

<script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.18.0/cdn/components/tree-item/tree-item.js"></script>

To import this component from the CDN using a JavaScript import: 

import 'https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.18.0/cdn/components/tree-item/tree-item.js';

To import this component using a bundler:

import '@shoelace-style/shoelace/dist/components/tree-item/tree-item.js';

To import this component as a React component:

import SlTreeItem from '@shoelace-style/shoelace/dist/react/tree-item';

Slots

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

Learn more about using slots.

Properties

Name Description Reflects Type Default
expanded Expands the tree item. boolean false
selected Draws the tree item in a selected state. boolean false
disabled Disables the tree item. boolean false
lazy Enables lazy loading behavior. boolean false
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
sl-expand onSlExpand Emitted when the tree item expands. -
sl-after-expand onSlAfterExpand Emitted after the tree item expands and all animations are complete. -
sl-collapse onSlCollapse Emitted when the tree item collapses. -
sl-after-collapse onSlAfterCollapse Emitted after the tree item collapses and all animations are complete. -
sl-lazy-change onSlLazyChange Emitted when the tree item’s lazy state changes. -
sl-lazy-load onSlLazyLoad Emitted when a lazy item is selected. Use this event to asynchronously load data and append items to the tree before expanding. After appending new items, remove the lazy attribute to remove the loading state and update the tree. -

Learn more about events.

Methods

Name Description Arguments
getChildrenItems() Gets all the nested tree items in this node. { includeDisabled = true }: { includeDisabled?: boolean }

Learn more about methods.

Parts

Name Description
base The component’s base wrapper.
item The tree item’s container. This element wraps everything except slotted tree item children.
item--disabled Applied when the tree item is disabled.
item--expanded Applied when the tree item is expanded.
item--indeterminate Applied when the selection is indeterminate.
item--selected Applied when the tree item is selected.
indentation The tree item’s indentation container.
expand-button The container that wraps the tree item’s expand button and spinner.
spinner The spinner that shows when a lazy tree item is in the loading state.
spinner__base The spinner’s base part.
label The tree item’s label.
children The container that wraps the tree item’s nested children.
checkbox The checkbox that shows when using multiselect.
checkbox__base The checkbox’s exported base part.
checkbox__control The checkbox’s exported control part.
checkbox__control--checked The checkbox’s exported control--checked part.
checkbox__control--indeterminate The checkbox’s exported control--indeterminate part.
checkbox__checked-icon The checkbox’s exported checked-icon part.
checkbox__indeterminate-icon The checkbox’s exported indeterminate-icon part.
checkbox__label The checkbox’s exported label part.

Learn more about customizing CSS parts.

Dependencies

This component automatically imports the following dependencies.

  • <sl-checkbox>
  • <sl-icon>
  • <sl-spinner>