ZingChart: Adding Standalone Labels to a Chart

When creating a chart, there are only so many places to display data - you have scales (axes), tooltips and crosshairs for when hovering over nodes, titles and subtitles, etc. But what if you want to display additional data? Where should you put it?

Thats where labels come in! Labels provide a handy way to display additional chart information, wherever you'd like! Labels are completely customizable - they can exist statically on top of/next to a chart or dynamically hooked to a scale/node, they can have static or dynamic text, and you can even include full HTML! Let's take a look at some examples of labels.

Standalone Labels

To create a label, first add a labels array to your graph object. This will act as a container for your label objects. Then, create an object with, at the very least, a text attribute specifying the label text. It should look like the below:

{
  // chart configuration
  labels: [
    {
      text: 'Label Text'
    }
  ],
  // chart configuration
}

Take a look at the following example, which uses four individual labels:

A pie chart with 4 labels explaining the data

The label configuration for the above is:

labels: [ 
  // Label 1 
  { 
    text: "35%", 
    'font-family': "Georgia", 
    'font-size': "50", 
    x: "60%", 
    y: "20%" 
  }, 
  // Label 2 
  { 
    text: "of surveyed users prefer the color", 
    'font-family': "Georgia", 
    'font-size': "12", 
    x: "60%", 
    y: "40%" 
  }, 
  // Label 3 
  { 
    text: "blue", 
    'font-color': "#29A2CC", 
    'font-family': "Georgia", 
    'font-size': "40", 
    x: "60%", 
    y: "45%" 
  }, 
  // Label 4 
  { 
    text: "over other colors.", 
    'font-family': "Georgia", 
    'font-size': "12", 
    x: "60%", 
    y: "60%" 
  } 
]

There are many different attributes you can use to style and place the label - font style and x/y placement is just the beginning! You can use background images, set the label to be clickable to any URL, or utilize any ZingChart tokens to dynamically pull text from chart data. Check the Labels JSON configuration page for a full list of available attributes.

Dynamic Labels

To make the labels more dynamically, you can hook them to a node or scale. That means you can set a label to be placed with a specific node or scale item instead of placed with x/y positioning.

To hook a label, add a hook attribute. Then, use the syntax in the following table:

Hook Placement	Syntax
Node	`'node:plot=x;index=y'` Where `x` is the index of the plot and `y` is the index of the node
Scale	`'scale:value=x'` Where `x` is a UNIX timestamp value (in milliseconds). For time-series charts.
Scale	`'scale:index=x'` Where `x` is the scale index. Applies to all scales.
Scale	`'scale:name=x;index=y'` Where `x` is the name of the scale and `y` is the scale index

The following demo shows dynamic node hook placement:

A scatter chart that will display a label when a node is clicked on.

The following demo shows the different types of scale hook placement:

A scatter chart with labels hooked to indices, unix timestamps, and scale values.

Summary

It's super easy to add custom labels to your chart, and make them dynamic if you want to! If you have any questions, feel free to ask us in chat!

ZingChart: Adding Standalone Labels to a Chart

Standalone Labels

Dynamic Labels

Summary

Related Documentation