Tableau UI for Angular

Tree

A tree shows nodes in levels; a node opens to show its children.

Import

Import TableauUiTreeModule from tableau-ui-angular/tree.

A tree

A tab-tree holds tab-tree-node elements, and in the default auto mode a node inside another is its child. A node with children opens and closes with a click on its button or anywhere in its row, and with the keys Accessibility below lists. Nodes start closed: [expanded] opens one, and (expandedChange) emits when the user opens or closes it, with a click or a key. Name each tree with aria-label or aria-labelledby on tab-tree.

Node 3
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { TableauUiTreeModule } from 'tableau-ui-angular/tree';

interface TreeItem {
  name: string;
  children: TreeItem[];
}

const leaf = (name: string): TreeItem => ({ name, children: [] });

@Component({
  selector: 'app-tree-basic-example',
  imports: [TableauUiTreeModule],
  templateUrl: './tree-basic.example.html',
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class TreeBasicExampleComponent {
  protected readonly nodes: TreeItem[] = [
    {
      name: 'Node 1',
      children: [
        { name: 'Subnode 1.1', children: [leaf('Subnode 1.1.1'), leaf('Subnode 1.1.2'), leaf('Subnode 1.1.3')] },
        { name: 'Subnode 1.2', children: [leaf('Subnode 1.2.1'), leaf('Subnode 1.2.2')] },
        leaf('Subnode 1.3'),
      ],
    },
    {
      name: 'Node 2',
      children: [{ name: 'Subnode 2.1', children: [leaf('Subnode 2.1.1'), leaf('Subnode 2.1.2')] }, leaf('Subnode 2.2')],
    },
    leaf('Node 3'),
  ];
}

Lines and buttons

The tree's inputs style its lines and its buttons. The lines are measured in the browser, so a page rendered on the server has none.

InputWhat it does
gridLinesBorderA CSS border, for a line from each node to its children; no lines by default
gridLinesBorderRadiusThe lines' corner; 0px by default
[showRootGridLines]Lines to the top level's nodes too, which then indent a level
childrenIndentEach level's indent; 1.4rem by default
expandButtonSize, expandButtonColorThe button's size, 1.2rem by default, and a CSS colour, which a node's own expandButtonColor overrides
expandButtonGapThe space between the button and the node's content; 0.2rem by default
expandButtonAlignThe button's place beside a tall node, an align-items value; center by default
[keepButtonOffsetOnNoChildren]Keeps the button's space on a node without children, so its content lines up with its siblings'; true by default
[expandButtonTooltip]The button's tooltips: expand, collapse, position and margin

A gap on the tree spaces its rows.

Node 1
Subnode 1.3
Node 3
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { TableauUiTreeModule } from 'tableau-ui-angular/tree';

interface TreeItem {
  name: string;
  children: TreeItem[];
}

const leaf = (name: string): TreeItem => ({ name, children: [] });

@Component({
  selector: 'app-tree-lines-example',
  imports: [TableauUiTreeModule],
  templateUrl: './tree-lines.example.html',
  styleUrl: './tree-lines.example.scss',
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class TreeLinesExampleComponent {
  protected readonly nodes: TreeItem[] = [
    {
      name: 'Node 1',
      children: [
        { name: 'Subnode 1.1', children: [leaf('Subnode 1.1.1'), leaf('Subnode 1.1.2'), leaf('Subnode 1.1.3')] },
        { name: 'Subnode 1.2', children: [leaf('Subnode 1.2.1'), leaf('Subnode 1.2.2')] },
        leaf('Subnode 1.3'),
      ],
    },
    {
      name: 'Node 2',
      children: [{ name: 'Subnode 2.1', children: [leaf('Subnode 2.1.1'), leaf('Subnode 2.1.2')] }, leaf('Subnode 2.2')],
    },
    leaf('Node 3'),
  ];
}
Node 1
Subnode 1.3
Node 3
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { TableauUiTreeModule } from 'tableau-ui-angular/tree';

interface TreeItem {
  name: string;
  children: TreeItem[];
}

const leaf = (name: string): TreeItem => ({ name, children: [] });

@Component({
  selector: 'app-tree-styled-example',
  imports: [TableauUiTreeModule],
  templateUrl: './tree-styled.example.html',
  styleUrl: './tree-styled.example.scss',
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class TreeStyledExampleComponent {
  protected readonly nodes: TreeItem[] = [
    {
      name: 'Node 1',
      children: [
        { name: 'Subnode 1.1', children: [leaf('Subnode 1.1.1'), leaf('Subnode 1.1.2'), leaf('Subnode 1.1.3')] },
        { name: 'Subnode 1.2', children: [leaf('Subnode 1.2.1'), leaf('Subnode 1.2.2')] },
        leaf('Subnode 1.3'),
      ],
    },
    {
      name: 'Node 2',
      children: [{ name: 'Subnode 2.1', children: [leaf('Subnode 2.1.1'), leaf('Subnode 2.1.2')] }, leaf('Subnode 2.2')],
    },
    leaf('Node 3'),
  ];
}

Open and closed content

In a node, an element marked expandedContent shows while the node is open, and one marked collapsedContent while it is closed. The rest of its content shows either way.

Node 1, open
Open: Subnode 1.1
Subnode 1.1.1
Subnode 1.1.2
Subnode 1.2
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { TableauUiTreeModule } from 'tableau-ui-angular/tree';

@Component({
  selector: 'app-tree-content-example',
  imports: [TableauUiTreeModule],
  templateUrl: './tree-content.example.html',
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class TreeContentExampleComponent {}

Nodes side by side

Nodes can also sit side by side: hierarchyId names a node, and hierarchyParentId its parent. An id is unique in its tree; a node with an id the tree already has is left out. [order] sorts the children of a parent, lower first and 0 by default; nodes with the same order keep their order in the template.

The tree's hierarchyMode says where a node's parent comes from:

ModeA node's parent
auto, the defaultThe node its hierarchyParentId names, or else the node it sits in
manualOnly the node its hierarchyParentId names: a node that names none is at the top level, wherever it sits
Node 3, last by its order
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { TableauUiTreeModule } from 'tableau-ui-angular/tree';

@Component({
  selector: 'app-tree-flat-example',
  imports: [TableauUiTreeModule],
  templateUrl: './tree-flat.example.html',
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class TreeFlatExampleComponent {}

Nodes in a component

A node finds its tree by injection, so a component inside tab-tree can hold nodes. A node that can't inject the tree joins it through [registry], given the tree's registry.

Music
import { ChangeDetectionStrategy, Component, input } from '@angular/core';
import { TableauUiTreeModule } from 'tableau-ui-angular/tree';

// A component that holds tree nodes: inside a tab-tree, its nodes find the tree
@Component({
  selector: 'app-tree-folder',
  imports: [TableauUiTreeModule],
  template: `
    <tab-tree-node>
      <span>{{ $name() }}</span>
      @for (file of $files(); track file) {
        <tab-tree-node>
          <span>{{ file }}</span>
        </tab-tree-node>
      }
    </tab-tree-node>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class TreeFolderComponent {
  readonly $name = input.required<string>({ alias: 'name' });
  readonly $files = input.required<string[]>({ alias: 'files' });
}

@Component({
  selector: 'app-tree-component-example',
  imports: [TableauUiTreeModule, TreeFolderComponent],
  templateUrl: './tree-component.example.html',
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class TreeComponentExampleComponent {}

Accessibility

The tree follows the WAI-ARIA tree view pattern. tab-tree is a tree, which the app names with aria-label or aria-labelledby on it. Each shown node's row is a treeitem with aria-level, 1 at the top whatever showRootGridLines, aria-setsize and aria-posinset among its siblings, and aria-expanded when it has children. The rows are siblings, so these carry the structure in place of nested groups.

The tree is one Tab stop: the first node at the start, then the node the user last moved to or clicked. The buttons that open and close the nodes take no focus and are hidden from screen readers, since the node says whether it is open. A click on a node's text, or anywhere else in its row, opens or closes a node with children and focuses it, as the activation of an assistive technology such as VoiceOver on iOS, TalkBack or Switch Control does. A click in a link, a button, a field, a label of a control or an element with a tabindex in the node's content is still that element's: make a clickable icon of your own a button, give it a tabindex, or stop its click's propagation. A control in a node's content keeps its own Tab stop and its own keys, and a click whose press selected text in the node toggles nothing.

Key on a nodeWhat it does
Down, UpThe next or previous shown node
RightOpens a closed node; on an open one, moves to its first child
LeftCloses an open node; on a child, moves to its parent
Home, EndThe first or last shown node
EnterOpens or closes a node with children
A characterThe next shown node whose text starts with it

When a node closes with the focus in one of its children, the focus moves to the node; when the focused node goes, to the shown node before it.