Skip to main content

Data Labels

Label and Token usage.

Enable Point Labels

Charts do not show labels by default, in order to show data labels either chart.defaultPoint.label.visible must be set to true or point.label.text must be specified like so:

{
  defaultPoint_label_text: "%yValue"
}

or

{
  defaultPoint_label_visible: true
}
Note: (NOTE: these property names are specified with one word, but are part of a hierarchy. This is possible due to the Code Expansion Tutorial feature of JSCharting).

Label Tokens

Label tokens are a powerful feature that allows specifying the syntax of your labels in a simple way. Tokens also provide common calculations that make specifying complex labels very simple. For example, the following data point label text can be used:

{
  defaultPoint_label_text: "%name:  %yValue  is %percentOfSeries% of %seriesName"
}

This setting will evaluate point labels to something similar to

Point A: 12 is 25% of Series 1

There are a number of token types. Point tokens, Series tokens, Series Collection Tokens, Value and Range tokens. Point labels use Point tokens, Legend entries use Series tokens, title text uses series collection tokens to summarize all the data on a chart, and axis ticks use value tokens.

Tokens can be used in virtually all labels including point labels, tooltips, URL, string events, legend and title text.

Reference:
Expressions Tutorial Create dynamic labels using expressions.
Token Reference Tutorial A complete list of available tokens.
Reference:
Expressions Tutorial Create dynamic labels using expressions.

Point Attribute Tokens

Point data can be specified with additional custom metadata. This data can then be referenced in labels by using tokens. For example, this code specifies two attributes for a point, a telephone number and an industry:

{
  series: [
    {
      name: "Series 1",
      points: [
        {
          name: "Mike Smith",
          y: 25,
          attributes: {
            tel: "(555) 555-5555",
            industry: "Automotive"
          }
        }
      ]
    }
  ]
}

These attributes can be used inside label text, tooltip, url, and any other point related strings.

{
  defaultPoint_label_text: "%name  %tel  <br> %industry "
}
Note: Notice the attribute names defined for this point can be used as tokens in labels.

This will result in the following label text:

Mike Smith (555)555-5555
Automotive
Reference:
Label Data Attributes Sample Demonstrates using attributes in labels.
Custom Attributes Tutorial Using custom point attributes.
Sample:
Label Data Attributes Sample Demonstrates using attributes in labels.

Label Callbacks

Label callbacks can also be used if more advanced label processing is necessary that requires code. It works by assigning a function to the label text property instead of a string. The function is called in context of the object it's assigned to, and a string return value is expected.

Sample:
Label Callbacks Sample Specifies callback functions for a number of labels as a demonstration.
Axis Shadowing Sample Uses label callbacks to recalculate axis tick labels into different units.

Evaluate tokens in callbacks

Point label callback functions get a parameter that is a reference to the point object itself. The point object has a replaceTokens() function that takes a string with tokens and returns the same string with the tokens replaced. For example, see the following code that sets a callback function:

options.defaultPoint_label_text = function(point) {
  var txt = "T:" + point.replaceTokens("{%percentOfTotal:n2}%");
  txt += "<br>S:" + point.replaceTokens("{%percentOfSeries:n2}%");
  return txt;
};

The resulting label of this callback will look something like:

T:5.34%
S:23.59%
Of course, the same can be achieved by simply using a string with the label as follows:

options.defaultPoint_label_text = "T:{%percentOfTotal:n2}% <br> S:{%percentOfSeries:n2}%";
Sample:
Label Callback Tokens Sample Demonstrates label callbacks.

Tokens can be evaluated within callbacks as well. However, label tokens when used with expressions can reduce if not completely eliminate the need for callback functions.

Reference:
Expressions Tutorial Create dynamic labels using expressions.

Other Features

A number of other label related features are available.

Unicode Support

Sample:
Label Unicode Sample Unicode characters