Skip to main content

Overview

The Tree class displays a hierarchical tree diagram with nodes connected by links. It extends LinkedHierarchy and uses the D3 tree layout algorithm to position nodes.
import * as am5hierarchy from "@amcharts/amcharts5/hierarchy";

const tree = root.container.children.push(
  am5hierarchy.Tree.new(root, {
    orientation: "vertical",
    inversed: false
  })
);

Class Hierarchy

  • Series
    • Hierarchy
      • LinkedHierarchy
        • Tree

Settings

orientation

orientation
'horizontal' | 'vertical'
default:"'vertical'"
Orientation of the diagram.
  • "vertical" - Tree grows from top to bottom
  • "horizontal" - Tree grows from left to right

inversed

inversed
boolean
default:"false"
If set to true, will flip the tree direction.For vertical orientation, this flips top-to-bottom to bottom-to-top. For horizontal orientation, this flips left-to-right to right-to-left.Since: 5.2.4

Inherited Settings

Tree inherits all settings from LinkedHierarchy and Hierarchy, including:
  • sort - How to sort nodes by value (“ascending” | “descending” | “none”)
  • valueField - Field in data holding numeric value
  • categoryField - Field in data holding category name
  • childDataField - Field in data holding array of children
  • downDepth - Number of child levels to show when drilling down
  • upDepth - Number of parent levels to show from selected node
  • initialDepth - Number of levels to show on first load
  • topDepth - Starting level to show (hides upper levels)
  • singleBranchOnly - Collapse other branches when one expands
  • animationDuration - Duration for drill animations in milliseconds
  • animationEasing - Easing function for animations
  • colors - ColorSet for auto-assigning node colors
  • patterns - PatternSet for auto-assigning node patterns
  • linkWithField - Field holding IDs of nodes to link with

Data Item Properties

Each data item in a Tree chart has the following properties:

children

children
Array<DataItem<ITreeDataItem>>
An array of children data items.

parent

parent
DataItem<ITreeDataItem>
Parent data item.

value

value
number
Value of the node as set in data.

sum

sum
number
Sum of child values.

valuePercentTotal

valuePercentTotal
number
Percent value of the node, based on total sum of all nodes in upper level.

valuePercent

valuePercent
number
Percent value of the node, based on the value of its direct parent.Since: 5.2.21

category

category
string
Category name of the node.

depth

depth
number
Node’s depth within the hierarchy (0 for root).

node

node
LinkedHierarchyNode
Reference to the visual LinkedHierarchyNode element.

circle

circle
Circle
Circle element of the node.

outerCircle

outerCircle
Circle
Outer circle element of the node (shown for nodes with children).

label

label
Label
Reference to node’s Label element.

fill

fill
Color
Node’s auto-assigned color.

fillPattern

fillPattern
Pattern
Node’s auto-assigned pattern.Since: 5.10.0

disabled

disabled
boolean
Indicates if node is currently disabled (collapsed).
HierarchyLink leading to parent node.
Array of HierarchyLink objects leading to child nodes.

linkWith

Array of IDs of directly linked nodes (for custom cross-links).

Data Format

interface ITreeDataObject {
  name?: string;
  value?: number;
  children?: ITreeDataObject[];
}

Example Data

tree.data.setAll([{
  name: "Root",
  value: 0,
  children: [
    {
      name: "Branch 1",
      value: 5,
      children: [
        { name: "Leaf 1.1", value: 2 },
        { name: "Leaf 1.2", value: 3 }
      ]
    },
    {
      name: "Branch 2",
      value: 8,
      children: [
        { name: "Leaf 2.1", value: 4 },
        { name: "Leaf 2.2", value: 4 }
      ]
    }
  ]
}]);

List Templates

Tree provides access to these list templates for customization:

nodes

nodes
ListTemplate<LinkedHierarchyNode>
List of all node elements. Use to customize node appearance and behavior.
tree.nodes.template.setAll({
  toggleKey: "disabled"
});

circles

circles
ListTemplate<Circle>
List of node circle elements. Use to customize circle appearance.
tree.circles.template.setAll({
  radius: 20,
  strokeWidth: 2
});

outerCircles

outerCircles
ListTemplate<Circle>
List of node outer circle elements (shown for nodes with children).
tree.outerCircles.template.setAll({
  strokeWidth: 3,
  strokeOpacity: 0.5
});

labels

labels
ListTemplate<Label>
List of label elements.
tree.labels.template.setAll({
  text: "{category}",
  fontSize: 12,
  centerX: am5.p50,
  centerY: am5.p50
});
List of link elements connecting nodes.
tree.links.template.setAll({
  strokeWidth: 2,
  strokeOpacity: 0.5
});

Containers

nodesContainer

nodesContainer
Container
Container that holds all node elements.
Container that holds all link elements.

Methods

selectDataItem()

selectDataItem(dataItem: DataItem<ITreeDataItem>): void
Selects a specific data item, triggering drill-down animation.
dataItem
DataItem<ITreeDataItem>
The data item to select.

getDataItemById()

getDataItemById(id: string): DataItem<ITreeDataItem> | undefined
Looks up and returns a data item by its ID.
id
string
The ID to search for.
return
DataItem<ITreeDataItem> | undefined
The found data item, or undefined if not found.

linkDataItems()

linkDataItems(
  source: DataItem<ITreeDataItem>,
  target: DataItem<ITreeDataItem>,
  strength?: number
): HierarchyLink
Creates a link between two data items.
source
DataItem<ITreeDataItem>
Source node data item.
target
DataItem<ITreeDataItem>
Target node data item.
strength
number
Optional link strength.
return
HierarchyLink
The created or existing link element.

unlinkDataItems()

unlinkDataItems(
  source: DataItem<ITreeDataItem>,
  target: DataItem<ITreeDataItem>
): void
Removes a link between two data items.
source
DataItem<ITreeDataItem>
Source node data item.
target
DataItem<ITreeDataItem>
Target node data item.

areLinked()

areLinked(
  source: DataItem<ITreeDataItem>,
  target: DataItem<ITreeDataItem>
): boolean
Returns true if two nodes are linked with each other.
source
DataItem<ITreeDataItem>
Source node data item.
target
DataItem<ITreeDataItem>
Target node data item.
return
boolean
True if nodes are linked, false otherwise.

enableDataItem()

enableDataItem(
  dataItem: DataItem<ITreeDataItem>,
  maxDepth?: number,
  depth?: number,
  duration?: number
): void
Enables a disabled (collapsed) data item.
dataItem
DataItem<ITreeDataItem>
Target data item to enable.
maxDepth
number
Maximum depth to enable children to.
depth
number
Current depth (used internally for recursion).
duration
number
Animation duration in milliseconds.

disableDataItem()

disableDataItem(
  dataItem: DataItem<ITreeDataItem>,
  duration?: number
): void
Disables (collapses) a data item.
dataItem
DataItem<ITreeDataItem>
Target data item to disable.
duration
number
Animation duration in milliseconds.

addChildData()

addChildData(
  dataItem: DataItem<ITreeDataItem>,
  data: Array<any>
): void
Adds children data to the target data item dynamically.
dataItem
DataItem<ITreeDataItem>
Parent data item to add children to.
data
Array<any>
Array of child data objects.
Since: 5.4.5

hoverDataItem()

hoverDataItem(dataItem: DataItem<ITreeDataItem>): void
Triggers hover state on a data item.
dataItem
DataItem<ITreeDataItem>
Target data item.
Since: 5.0.7

unhoverDataItem()

unhoverDataItem(dataItem: DataItem<ITreeDataItem>): void
Removes hover state from a data item.
dataItem
DataItem<ITreeDataItem>
Target data item.
Since: 5.0.7

Events

dataitemselected

tree.events.on("dataitemselected", (ev) => {
  console.log("Selected:", ev.dataItem);
});
Fired when a data item is selected.
dataItem
DataItem<ITreeDataItem> | undefined
The selected data item.

Private Settings

These are read-only private settings managed internally:

scaleX

scaleX
number
Current horizontal scale.

scaleY

scaleY
number
Current vertical scale.

See Also

Build docs developers (and LLMs) love