Tree Charts

Note: See our Tree Module Gallery for inspiration on all the different tree chart possibilities.

Tree Chart Type

To specify the chart type, add a type attribute to the chart object. Our standard tree chart (aka network diagram) is specified by the tree value.

{
  type: 'tree'
}

Graph Tree Chart

To create a graph tree chart, set aspect: 'graph in the options object. Graph tree charts have a specific way of entering and linking node data.

https://app.zingsoft.com/demos/embed/9XUP49R1
https://app.zingsoft.com/demos/embed/9XUP49R1

Family Nodes

For this type of tree chart, there will be a main node (family node) object that will link to other nodes that will contain the information, such as the images. Family node objects will have a few attributes needed for it to work. First, you'll need to add the type attribute with a value of 'node' to your series array, meaning each series will be a floating node.

Each object will also need the id attribute. This main node holds the family trees together and will be called n1, n2, n3 and so forth.

Note: You can include an optional cls attribute to set a class on the object for styling (discussed further below).

A standard family node will take this format:

{
  type: 'node', 
  id: 'n1', 
  cls : 'fam', //optional class for styling
  text: '', //optional text for label- empty string value for family nodes
  dataFullname: '' //optional custom token- empty string value for family nodes
}

With each new family or group on the graph tree charts, we need to have a new hub node so that the families will have their own hub to link to (the id values of n1, n2 and so forth). The best way to organize these for ease of reading and use would be to have the main hub series above the same family series that will be tied to that hub. An example is:

{
  series: [
    { // main node hub 1
      type: 'node',
      id: 'n1',
      cls: 'fam',
      text: ' ',
      dataFullName: ''
    },
    {
      type: 'node',
      id: 'Ned Stark',
    },
    {
      type: 'node',
      id: 'Brandon Stark',
      text: 'Brandon',
      dataFullName: 'Brandon Stark',
    },
    { // main node hub 2
      type: 'node',
      id: 'n2',
      cls: 'fam',
      text: ' ',
      dataFullName: ''
    },
    {
      type: 'node',
      id: 'Lyarra Stark',
    },
  ]
}

Data Nodes

With each main node hub, we can link other data objects to it. The data node objects will have a few attributes that we need to fill out, the first being type: 'node'. Furthermore, we need to assign an id to this object so that we can target and link it to the hub nodes. The id attribute for data nodes can be assigned anything and will most likely describe what the data node represents.

Adding a text attribute will give your node a label. dataFullname is a custom token that can be used to display more information in your tooltips. For family node objects, these attributes take empty strings as values.

Note: You can include an optional cls attribute to set a class on the object for styling (discussed further below).

A standard data node will take this format:

{
  series: [
    { //data node object
      type: 'node',
      id: 'Ned Stark',
      text: 'Ned',
      dataFullName: 'Ned Stark',
    },
  ]
}

Link Objects

Once we have our families and data nodes set, we can link them together using link objects in the same series array. First, you'll need the type attribute with a value of 'link'.

Link objects will target the id attribute and draw a link from the source value to the target value. In our case, the source will be the main node hubs of n1, n2 and n3, and the target will be the id of data nodes.

Every data node will need a link object so that it will be connected to the chosen hub node. A data node can be linked to multiple family trees by linking them to multiple hub nodes.

{
  series:[
    {
      type: 'link',
      source: 'n1',
      target: 'Ned Stark'
    },
  ]
}

Link-Node Attraction and Interactions

For graph tree charts, the springLength, attractionConstant, repulsionConstant, and repulsionDistanceFactor attributes will determine the length, repulsion, attraction and interactions of the links and nodes.

The attractionConstant and repulsionConstant attributes are used to determine the amount of magnetization between each node in a graph tree chart . The constants used in the Game of Thrones demo gives the graph tree chart a balanced amount of distance and attraction:

{
  options: {
    aspect: 'graph',
    springLength: 75,
    attractionConstant: 0.8,
    repulsionConstant: 4000,
    repulsionDistanceFactor: 20,
  }
}

Node Styling

To style individual nodes, create a style object within the applicable series object. This is where we will be able to set the backgroundImage, size and many other ZingChart styling basics for the nodes.

Note: When using backgroundImage, it is useful to use background-fit: 'xy' so that the image will be centered and show properly inside the small node area.

Note: Learn more about styling nodes with our Chart Plot & Series Styling Tutorial.

{
  series:[
    {
      type: 'node',
      style: {
        "background-fit": "xy",
        backgroundImage: "https://i.imgur.com/OFrvsvv.png"
      }
    },
  ]
}

To style hub nodes, use the node[cls-fam] object inside the options object. node[cls-fam] can take the same attributes as the node objects except that it will target the hub nodes instead of the data nodes. The cls-fam nomenclature stems from how we set the series array in the tree chart.

{
  options:{
    'node[cls-fam]': {
      size: 12,
      borderWidth: 2,
      borderColor: '#000',
      backgroundColor: 'white',
      label: {
        visible: false
      }
    },
  }
}

Organizational Diagram

To create an organizational diagram, set aspect: 'tree-down in the options object. This is how the organizational chart knows where the parent nodes will start from. You'll also need an orgChart attribute set to true for the organizational charts to function.

Note: You can also set the aspect to 'tree-up', 'tree-right', or 'tree-left, but 'tree-down' is the most commonly used.

{
  options: {
		aspect : 'tree-down',
		orgChart : true,
  }
}
https://app.zingsoft.com/demos/embed/ESLV96RQ
https://app.zingsoft.com/demos/embed/ESLV96RQ

Organizational Diagram Data

Each object in the series array for organizational charts correspond to a node. Each will need an id and name attribute.

These id attributes will be used to target the nodes for parent and sibling attributes that some nodes will contain. The parent attribute and sibling attribute is how we link different nodes together.

Lastly, you'll want to add a cls attribute. This attribute is set to a variable which can then be targeted in the chart JSON so that the individual nodes can be styled.

{
  series: [
    {
      id: 'execasspres',
      name: 'Executive Assistant to<br>the President',
      parent: 'collegeboard',
      sibling: 'president',
      cls: 'bwhite'
    },
  ]
}

Data

Provide your chart data in the series array. In the array, create an object and assign a value to the id, parent, name, and value, attributes. Alternatively, you can use the group attribute instead of the parent attribute.

id is the node id; parent specifies the parent node id; name is the label of the node; and value is the numerical value of the node object being added. Instead of parent, you can use group to specify which group the node is placed in.

{
  series: [
    {
      id: 'theworld',
      parent: '',
      name: 'The World',
    },
    {
      id: 'asia',
      parent: 'theworld',
      name: 'Asia',
      value: 4100000000
    },
  ]
}

Chart-Specific Properties

Style and customize your tree chart with certain attributes on the options object or dynamically through our API.

Detaching Nodes

You can detach nodes/groups in your diagram dynamically through our API or on render.

// function to separate group from tree diagram
function removeNodeById(id) {
  zingchart.exec('myChart', 'tree.removenode', {
    id,
  });
}
https://app.zingsoft.com/demos/embed/4S9FUH2M
https://app.zingsoft.com/demos/embed/4S9FUH2M

Collapsible Nodes

Collapsible nodes are enabled on tree charts by default. Enable them manually with a weightedLinks attribute in the options object. Enter a value of 0 for true (default) or 1 for false.

{
  options: {
    weightedLinks: 0, // set to 1 to disable collapsible nodes
  }
}
https://app.zingsoft.com/demos/embed/KR6IA1Z7
https://app.zingsoft.com/demos/embed/KR6IA1Z7

Further Customization

Once you have your basic chart, you can customize and style it to fit your data visualization needs.

Node Connectors

Customize the lines that connect nodes with the link object. Include an aspect attribute with any of these values: arc (default), sibling, side-before, side-after, side-between, split, line.

options: {
  link: {
    aspect: 'arc', // sibling, side-before, side-after, side-between, split, line 
  }
}

Nodes

The node object is where the general styling of the nodes is. You can adjust the type, color, shape, size, hover effects here.

Note: Node types are based on ZingChart shapes. Learn more with our Shapes Tutorial.

node: {
  type: 'circle',
  borderWidth: '0px',
  hoverState: {
    borderAlpha: 1,
    borderColor: '#000',
    borderWidth: '2px'
  },
  label: {
    width: '100px'
  },
  tooltip: {}
}

Tokens

Below is a short list of all the available tokens for tree charts:

TokenDescription
%textThe chart's text attribute.
%valueThe nodes overall value.
%data-xxxCustom token to be accessed.

Tooltip

You can adjust the tooltip value with the node.tooltip object. This object carries all standard styling from the tooltip object.

node: {
  tooltip: {
    padding: '8px 15px',
    text: 'My %text has a value of: %value'
  }
}

Note: Learn more about tooltips with our Tooltips Tutorial. For more tooltip styling options, see our Tooltips JSON Attributes/Syntax page.

Events

Events for clicking nodes will NOT be node_click, and instead will be shape_click because at the core, network diagrams are class shapes and not nodes.

shape_click

Use the shape_click event to fire clicking on nodes and clusters for network diagrams. You can view our object events documentation for more information.

shape_mouseover

Use the shape_mouseover event to fire hovering on nodes. You can view our object events documentation for more information.

https://app.zingsoft.com/demos/embed/2CE2GU9F
https://app.zingsoft.com/demos/embed/2CE2GU9F

Methods

To update the tree, you must use the setdata method.

zingchart.exec('myChart', 'setdata', {
  data: chartConfigObj
});

Summary

Have questions about how tree charts/ network diagrams work? We're happy to help! Email support@zingchart.com or start a chat right here on this page for support.