Tree

When to use

The following guidance describes when to use the tree component.

Hierarchical Content

The Tree is ideal for displaying and navigating hierarchical data, such as file systems or category structures. It groups related data with nested relationships in a clear and organized way. It is a powerful tool for organizing subject lesson content in educational applications. For example, it represents a syllabus with modules as parent nodes and lessons as child nodes, enabling students to intuitively explore and navigate their coursework.

Collapsible Data

The Tree allows users to dynamically expand or collapse data sections, enabling a cleaner interface that focuses only on relevant information. This interactive functionality is handy when managing large amounts of content, where each item contains complex data or detailed information. It ensures users can explore deeply without being overwhelmed.

When not to use

Global Navigation

Do not use Tree as the primary navigation for your product’s UI. The tree component is not suitable for this purpose.

Elements Toggle

The tree is not ideal for showing and hiding UI elements or content within a page. If the interaction only involves collapsing or expanding content at a basic level, consider using other components like accordions or collapsible panels for a more straightforward solution.

Anatomy

Variants

Tree comes in three versions, each suited for specific situations:

Node

A basic element in the tree, representing a terminal item without parent or child nodes.

Parent Node

A node that has one or more child nodes, typically expandable to reveal more detailed data.

Child Node

A node nested under a parent node, typically hidden until the parent is expanded, representing more detailed or lower-level information.

Figma Options

With these options, you can tweak the appearance of the Tree in Figma. They are available in the Design Panel so you can compose the switch to exactly fit the user experience need for the use case you are working on.

Behaviour

Let's explore the behaviour of the Tree.

Selectable

When this feature is enabled, nodes can be selected by the user, allowing for interactions such as checking, highlighting, or performing actions on a specific node.

Multiple Selection

When this feature is enabled, users can select multiple nodes at the same time, allowing interactions such as checking, highlighting, or performing actions on several nodes simultaneously. Single selection is disabled in this mode to simplify user interaction.

Expandable

Allowing users to click on a parent node to reveal its child nodes. This interaction helps in navigating deeper structures without overwhelming the user with too much data at once. It is essential for managing large hierarchical datasets.

Indentation

Indentation visually distinguishes parent nodes from their child nodes by shifting them to the right. This hierarchy helps users understand the relationship between different levels of the data quickly.

Related Components

• Badge
• Checkbox
• Icon

Tree data source

The tree component requires a data source to supply structure and manage state. This component provides FlatTreeDataSource, which adapts a flat array to a hierarchical view, and NestedTreeDataSource, which works directly with nested tree-structured data.

What is a data source?

A data source is an adapter that normalizes your raw data into the view model that UI components use. It centralizes filtering, sorting, selection, and emits events when its state changes. Multiple components (e.g. tree, grid, paginator) share the same base DataSource so behaviour stays consistent.

For tree, FlatTreeDataSource extends the base and maps a flat array with a level field into a hierarchical view while tracking expansion and selection. Alternatively, you can use NestedTreeDataSource if your data is already structured as a nested tree, allowing you to work directly with hierarchical data without flattening it first. Both extend the base TreeDataSource.

Both tree data sources do not enforce a specific data shape. Instead, you provide callback functions to extract ids, labels, levels, children, and expansion state from your items. The data source will use these callbacks to build the tree structure and manage state.

export interface TreeDataSourceMapping<T> {
  /** Optional method for returning a custom aria description for a tree node. */
  getAriaDescription?(item: T): string | undefined;

  /**
   * Returns the number of children. This can be used in combination with
   * lazy loading children. This way, the tree component can show skeletons
   * for the children while they are being loaded.
   */
  getChildrenCount?(item: T): number | undefined;

  /** Optional method for returning a custom icon for a tree node. */
  getIcon?(item: T, expanded: boolean): string;

  /** Used to identify a tree node. */
  getId(item: T): unknown;

  /**
   * Returns a string that is used as the label for the tree node.
   * If you want to customize how the tree node is rendered, you can
   * provide your own `TreeItemRenderer` function to the tree component.
   */
  getLabel(item: T): string;

  /** Returns whether the given node is expandable. */
  isExpandable(item: T): boolean;

  /**
   * Returns whether the given node is expanded. This is only used for the initial
   * expanded state of the node. If you want to expand/collapse a node programmatically,
   * use the `expand` and `collapse` methods on the data source.
   */
  isExpanded?(item: T): boolean;

  /**
   * Returns whether the given node is selected. This is only used for the initial
   * selected state of the node. If you want to select/deselect a node programmatically,
   * use the `select` and `deselect` methods on the data source.
   */
  isSelected?(item: T): boolean;
}

Depending on whether you use FlatTreeDataSource or NestedTreeDataSource, you will need to provide additional mapping functions:

export interface FlatTreeDataSourceMapping<T> extends TreeDataSourceMapping<T> {
  /** Returns the level in the tree of the given item. */
  getLevel(item: T): number;
}

or

export interface NestedTreeDataSourceMapping<T> extends TreeDataSourceMapping<T> {
  /** Returns the children of the given item. */
  getChildren(item: T): T[] | Promise<T[]> | undefined;
}

Custom renderer

The tree component renders the tree nodes by default using the label and icon provided by the data source. It does this using a virtual list, so it can efficiently render large trees. This also means that you cannot use regular slot-based templating to customize the rendering of tree nodes.

The tree component provides a renderer callback function that supports custom rendering of nodes. This allows you to add custom icons, buttons, or other interactive elements to each node.

const renderer = node => {
  // Don't show action buttons for expandable nodes; returning undefined
  // will make the tree use the default rendering.
  if (node.expandable) {
    return undefined;
  }

  const onClick = (event: Event) => event.stopPropagation();

  return html`
    <span>${node.label}</span>

    <sl-button @click=${onClick} aria-label="Edit" slot="actions">
      <sl-icon name="far-pen"></sl-icon>
    </sl-button>
    <sl-button @click=${onClick} aria-label="Remove" slot="actions">
      <sl-icon name="far-trash"></sl-icon>
    </sl-button>
  `;
};

Do not forget to specify any scoped elements you use in your renderer in the scopedElements property of the <sl-tree> component.

const tree = document.querySelector('sl-tree');
tree.renderer = renderer;
tree.scopedElements = { 'sl-button': Button };

Some, such as <sl-icon>, are already included by default.

API

The tree API exposes a comprehensive set of properties, events, and customization options, enabling developers to tailor its behavior, appearance, and interaction patterns for diverse use cases.

Properties

Events

Keyboard interactions

WAI-ARIA

In the component itself we use multiple aria-attributes to assure the component works well with a range of assistive technologies. For some attributes however it is not possible for the Design System to add a meaningful value, because it relies on the context or way a component is used.

Attributes that we recommend you add in certain scenarios are mentioned below.

Tree