Text Formatters

Overview

Sometimes it might be necessary to display any text with the points on a chart for some reasons. That's when you need to use the .textFormatter() method.

String Tokens

String tokens are special strings you can use in text formatters instead of using formatting functions described later, string tokens are suitable when you need only basic formatting, but they cover most of the cases.

Here is how tokens can be used in tooltips, series labels or axes labels:

anychart.onDocumentReady(function() {
  // chart type
  var chart = anychart.column([
  {x: 'January', value: -10, season:"Winter"},
  {x: 'February', value: -8, season:"Winter"},
  {x: 'March', value: -4, season:"Spring"},
  {x: 'April', value: 1, season:"Spring"},  
  {x: 'May', value: 7, season:"Spring"},  
  {x: 'June', value: 12, season:"Summer"}
    ]);

  // set tooltip text template
  var tooltip = chart.getSeries(0).tooltip();
  tooltip.title().text("Content");
  tooltip.textFormatter("{%x} is a {%season} month\nLowest temp: {%Value}°C");

  // set series labels text template
  var seriesLabels = chart.getSeries(0).labels().enabled(true);
  seriesLabels.textFormatter("{%x}");
  
  // format axis labels
  var axisLabels = chart.xAxis().labels();
  axisLabels.useHtml(true);
  axisLabels.textFormatter("<b style='color:black;'>{%Value}</b>");

  // draw
  chart.container("container");
  chart.draw();
});

A live sample of chart tooltip, labels and axes labels formatted using string tokens:

JsFiddle Playground

Tokens List

Here is a full list of the tokens you can use in formatting strings, note that some tokens don't work unversally: you can't use {%BubbleSize} outside of Bubble series or {%Close} outside of Candlestick or OHLC and so on.

Token Description
{%Value}The y value of this point.
{%YValue}The y value of this point.
{%YPercentOfSeries}The percentage of the series this point represents.
{%YPercentOfTotal}The percentage of all the series on the chart this point represents.
{%XValue}The x value of this point (Scatter Plot charts).
{%BubbleSize}The bubble size value of this point (Bubble chart).
{%Index}The index of this point in the series this point represents (zero-based).
{%SeriesName}The name of this series.
{%SeriesYSum}The sum of all the points y values.
{%SeriesYAverage}The average y value of all the points within this series.
{%SeriesPointCount} number of points in this series.
{%Name}The name of this point.
{%High}The high value of this point (OHLC, Candlestick).
{%Low}The low value of this point (OHLC, Candlestick).
{%Open}The open value of this point (OHLC, Candlestick).
{%Close}The close value of this point (OHLC, Candlestick).
{%SeriesYMax}The maximal y value of all the elements within this series.
{%SeriesYMin}The minimal y value of all the elements within this series.
{%RangeStart}The starting value of this point (Range charts).
{%RangeEnd}The ending value of this point (Range charts).
{%Range}The range of this point (RangeEnd - RangeStart).
{%DataPlotYSum}The sum of all the points y values.
{%DataPlotYMax}The maximal of all the points y values.
{%DataPlotYMin}The minimal of all the points y values.
{%DataPlotYAverage}The average y value of all the points.
{%DataPlotPointCount}The number of the points within the chart.
{%DataPlotSeriesCount}The number of the series within the chart.

Formatting functions

If you need a complex formatting you can use formatting function instead of token strings. Formatting functions are set like this:

    //set data series
    var series = chart.bar(Sales2003);
    series.name("Winter");
    
    series.tooltip().textFormatter(function(){
        return this.seriesName + ": " + this.value + " millions%";
    });

Default fields

There are some standard fields available in formatters depending on a chart type. Below you can see a table with all chart types and fields available for them by default.

Chart type(s)Default fields of series.labels().textFormatter()
Area
Bar
Column
Error
Marker
Percent Stacked Area
Percent Spline Area
Percent StepLine Area
Percent Stacked Bar
Percent Stacked Column
Polar
Radar
Sparkline
Stacked Line
Stacked Spline
x
value
seriesName
index
Range Line
Range Spline Area
Range Column
Range Bar
x
seriesName
index
high
low
Scatter x
seriesName
index
value
valueLowerError
valueUpperError
xLowerError
xUpperError
Bubble x
value
seriesName
size
Box x
seriesName
index
lowest
q1
median
q3
highest
outliers
Japanese Candlestick
Open-High-Low-Close
x
open
high
low
close
seriesName
index
Pie/Donut
Funnel
Pyramid
Note! As those types have an only series by default,
you should use the .textFormatter() method with chart.label().
x
value
index

Let's look at those examples to understand how it works.

    //set data series
    var series_1 = chart.bar(Sales2003);
    var series_2 = chart.bar(Sales2004);
    
    //set series name
    series_1.name("Winter");
    series_2.name("Summer");
    
    //set textFormatter
    var labels_1 = series_1.labels();
    labels_1.enabled(true);
    labels_1.textFormatter(function(){
        return(this.seriesName);
    });
    var labels_2 = series_2.labels();
    labels_2.enabled(true);
    labels_2.textFormatter(function(){
        return(this.seriesName);
    });

JsFiddle Playground

First of all, you should enable the labels. Then set the fields of values you want those labels to show using the .textFormatter() function according to the table above.

This function can return more than one value. The sample below demonstrates it.

    //set the textFormatter
    var labels_1 = series_1.labels();
    labels_1.textFormatter(function(){
        return("Size: "+this.size+", value: "+this.value);
    });
    var labels_2 = series_2.labels();
    labels_2.textFormatter(function(){
        return("Size: "+this.size+", value: "+this.value);
    });

JsFiddle Playground

Extra fields

The number and variety of default fields might be not enough in some cases. Sometimes it's necessary to show some extra information. In this case you should use one of the following methods: .getStat(), .getDataValue() or .getSeriesMeta(). Which one to use depends on the unique situation.

getDataValue

Using these methods, you can display the values from the extra params, if you have added any to the series or to the data. Look at the sample and its code below:

    //create box chart series with our data
    var series_1 = chart.box(data_1);
    var series_2 = chart.box(data_2);

    //enable the labels
    var labels = series_2.labels();
    labels.enabled(true);

    //usage of textFormatter
    labels.textFormatter(function(){
        return(this.getDataValue("extra_inf"));
    });

JsFiddle Playground

In this sample we have added some extra information to the data: we defined the "extra_inf" parameter of "redundant" value for the second point of the second series and displayed it, using .getDataValue().

Managing additional information for chart tooltips works pretty much the same as it does for chart labels. Define extra parameter in your data set and use the name of your parameter as a value for .getDataValue() method.

    // map data for series
    var seriesData = dataSet.mapAs({
        // set data row for x parameter
        x: [0],
        // set data row for value parameter
        value: [1],
        // set data row for custom parameter
        yoy: [2]
    });

    // set data for series
    var series = chart.column(seriesData);
    series.name("Unique users in 2013");

    // series tooltip settings
    var tooltip = series.tooltip();
    // adjust tooltip text
    tooltip.textFormatter(function(){
        return
            this.seriesName + ": " + this.value + " millions" +
            "\nYear over year: " + this.getDataValue("yoy") + "%";
    });

Here is a sample with additional information in the chart tooltip. Full information on tooltip settings can be found in Tooltip article.

JsFiddle Playground

getSeriesMeta

You can add extra parameters not only to the data points but to series too. Let's add an extra parameter as to the series of OHLC chart and show it with textFormatter.

To add any parameter to the meta of the series, you need to set the parameter name first and then its value, which can be of any type.


    // set first series data
    var series_1 = chart.ohlc([
        {x: Date.UTC(2007, 7, 28), open:511.53, high:514.98, low:505.79, close:506.40},
        {x: Date.UTC(2007, 7, 30), open:517.36, high:518.40, low:516.58, close:516.80},
        {x: Date.UTC(2007, 8, 1), open:513.10, high:516.50, low:511.47, close:515.25},
    ]);
    series_1.xPointPosition(0.5);
    series_1.meta("company", "ACME Corp.");
     
    // set second series data
    var series_2 = chart.ohlc([
        {x: Date.UTC(2007, 7, 28), open: 522.95, high: 523.10, low: 522.50, close: 522.52},
        {x: Date.UTC(2007, 7, 30), open: 524.49, high: 524.91, low: 524.38, close: 524.61},
        {x: Date.UTC(2007, 8, 1), open: 518.81, high: 520.03, low: 517.51, close: 519.73}
    ]);
    series_2.xPointPosition(0.5);
    series_2.meta("company", "Duff B. Corp.");

    //textFormatter
    var labels_1 = series_1.labels();
    labels_1.textFormatter(function(){
        return("C: "+this.getSeriesMeta("company")+"\nL: "+this.low+"\nH: "+this.high);
    });
    var labels_2 = series_2.labels();
    labels_2.textFormatter(function(){
        return("C: "+this.getSeriesMeta("company")+"\nL: "+this.low+"\nH: "+this.high);
    });

JsFiddle Playground

Note! There's no .getSeriesMeta() method in Pie, Funnel or Pyramid Charts.

getStat

This method is to be used when you need to display some statistic information. The variety of fields for this method is not complied the same way as shown above. The available fields for this method are given below.

Chart type(s)Default fields of series.labels().textFormatter()
Area
Bar
Box
Bubble
Column
Error
Marker
Percent Stacked Area
Percent Spline Area
Percent StepLine Area
Percent Stacked Bar
Percent Stacked Column
Polar
Radar
Range Line
Range Spline Area
Range Column
Range Bar
Scatter
Sparkline
Stacked Line
Stacked Spline
max - max value on a chart
min - min value on a chart
sum - sum of all values of a chart
average - average value on a chart
pointsCount - the number of all points on a chart
seriesMax - max value of the series
seriesMin - min value of the series
seriesSum - sum of all values of the series
seriesAverage - average value of the series
seriesPointsCount - the number of all points on a chart
Japanese Candlestick
Open-High-Low-Close
pointsCount - the number of all points on a chart
seriesPointsCount - the number of all points on a chart
Pie/Donut
Funnel
Pyramid
count - number of points
min - min value on a chart
max - max value on a chart
sum - sum of all values of a chart
average - average value (sum / count)

Here is a sample of the .getStat() method usage in the Pie chart. Note there's no need in enabling the labels for a Pie chart, because they are enabled by default.

    //textFormatter
    var labels = chart.labels();
    labels.textFormatter(function(){
        return((this.getDataValue("value"))+" / "+this.getStat("sum"));
    });

JsFiddle Playground

You are looking at an outdated 7.10.0 version of this document. Switch to the 8.0.1 version to see the up to date information.