Tree
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.
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.
| Input | What it does |
|---|---|
gridLinesBorder | A CSS border, for a line from each node to its children; no lines by default |
gridLinesBorderRadius | The lines' corner; 0px by default |
[showRootGridLines] | Lines to the top level's nodes too, which then indent a level |
childrenIndent | Each level's indent; 1.4rem by default |
expandButtonSize, expandButtonColor | The button's size, 1.2rem by default, and a CSS colour, which a node's own expandButtonColor overrides |
expandButtonGap | The space between the button and the node's content; 0.2rem by default |
expandButtonAlign | The 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.
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'),
];
}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.
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:
| Mode | A node's parent |
|---|---|
auto, the default | The node its hierarchyParentId names, or else the node it sits in |
manual | Only the node its hierarchyParentId names: a node that names none is at the top level, wherever it sits |
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.
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 node | What it does |
|---|---|
| Down, Up | The next or previous shown node |
| Right | Opens a closed node; on an open one, moves to its first child |
| Left | Closes an open node; on a child, moves to its parent |
| Home, End | The first or last shown node |
| Enter | Opens or closes a node with children |
| A character | The 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.