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 format() method.

String Tokens

String tokens are special string values you can use in text formatters instead of using formatting functions described below. They 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.format("{%x} is a {%season} month\nLowest temp: {%value}°C");

  // set series labels text template
  var seriesLabels = chart.getSeries(0).labels().enabled(true);
  seriesLabels.format("{%x}");
  
  // format axis labels
  var axisLabels = chart.xAxis().labels();
  axisLabels.useHtml(true);
  axisLabels.format("<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:

Playground

Tokens List

Here is the list of the tokens you can use in formatting strings. Note that some tokens don't work universally: you can't use {%bubbleSize} outside of Bubble series or {%close} outside of Candlestick or OHLC and so on.

The full list of tokens is available in API: anychart.enums.Statistics

Token Description
{%average}Average value.
{%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).
{%bubbleSizePercentOfCategory}The percentage of all the points with the same name this point represents (Categorized charts).
{%bubbleSizePercentOfSeries}The percentage of the series this point represents.
{%bubbleSizePercentOfTotal}The percentage of all the series on the chart this point represents.
{%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}The number of points in this series.
{%seriesBubbleMaxSize}The maximal bubble size value of all the points within this series (Bubble chart).
{%seriesBubbleMinSize}The minimal bubble size value of all the points within this series (Bubble chart).
{%seriesBubbleSizeAverage}The average bubble size value of all the points within this series (Bubble chart).
{%seriesBubbleSizeMedian}The median bubble size value of all the points within this series (Bubble chart).
{%seriesBubbleSizeMode}The mode bubble size value of all the points within this series (Bubble chart).
{%seriesBubbleSizeSum}The sum of all the points bubble sizes (Bubble chart).
{%SeriesFirstXValue}The x value of the first point in this series (Scatter plot charts).
{%seriesFirstYValue}The y value of the first point in this series.
{%seriesLastXValue}The x value of the last point in this series (Scatter plot charts).
{%seriesLastYValue}The y value of the first point in this series.
{%seriesXAverage}The average x value of all the points within this series.
{%seriesXAxisName}The title text of the X Axis.
{%seriesXMax}The maximal x value of all the elements within this series (Scatter plot charts).
{%seriesXMedian}The median x value of all the points within this series (Scatter plot charts).
{%seriesXMin}The minimal x value of all the elements within this series (Scatter plot charts).
{%seriesXMode}The mode x value of all the points within this series (Scatter plot charts).
{%seriesXSum}The sum of all the points x values (Scatter plot charts).
{%seriesYAxisName}The title text of the Y Axis.
{%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.
{%seriesYMedian}The median y value of all the points within this series.
{%seriesYMode}The mode y value of all the points within this series.
{%rangeStart}The starting value of this point (Range charts).
{%rangeEnd}The ending value of this point (Range charts).
{%seriesYRangeMax}The maximal range in this series (Range charts).
{%seriesYRangeMin}The minimal range in this series (Range charts).
{%seriesYRangeSum}The sum of all ranges in this series (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.
{%dataPlotBubbleMaxSize}The maximal of all the points bubble sizes (Bubble chart).
{%dataPlotBubbleMinSize}The minimal of all the points bubble sizes (Bubble chart).
{%dataPlotBubbleSizeAverage}The average bubble size of all the points (Scatter plot charts).
{%dataPlotBubbleSizeSum}The sum of all the points bubble sizes (Bubble chart).
{%dataPlotSeriesCount}The number of the series within the chart.
{%dataPlotXAverage}The average x value of all the points (Scatter plot charts).
{%dataPlotXMax}The maximal of all the points x values (Scatter plot chart).
{%dataPlotXMin}The minimal of all the points x values (Scatter plot chart).
{%dataPlotXSum}The sum of all the points x values (Scatter plot charts).
{%dataPlotYRangeMax}The maximal of the ranges of the points within the chart.
{%dataPlotYRangeMin}The minimal of the ranges of the points within the chart.
{%dataPlotYRangeSum}The sum of the ranges of the points within the chart.
{%axisName}The name of the axis.
{%axisScaleMax}The maximum value on the axis.
{%axisScaleMin}The minimum value on the axis.
{%categoryName}The name of the category.
{%categoryYAverage}The name of the category.
{%categoryYMedian}The median of all the points within this category.
{%categoryYMode}The mode of all the points within this category.
{%categoryYPercentOfTotal}The percent of all the data on the chart this category represents.
{%categoryYRangeAverage}The average range in this category (Range charts).
{%categoryYRangeMax}The maximal range in this category (Range charts).
{%categoryYRangeMedian}The median range in this category (Range charts).
{%categoryYRangeMin}The minimal range in this category (Range charts).
{%categoryYRangeMode}The mode range in this category (Range charts).
{%categoryYRangePercentOfTotal}Category Y range percent of total (Range charts).
{%categoryYRangeSum}The sum of all ranges in this category (Range charts).
{%categoryYSum}The sum of all the points within this category.
{%dataPlotMaxYSumSeriesName}The name of the series with a maximal sum of the points y values.
{%dataPlotMaxYValuePointName}The name of the point with a maximal of all the points y values.
{%dataPlotMaxYValuePointSeriesName}The name of the series with a maximal of all the points y values.
{%dataPlotMinYSumSeriesName}The name of the series with a minimal sum of the points y values.
{%dataPlotMinYValuePointName}The name of the point with a minimal of all the points y values.
{%dataPlotMinYValuePointSeriesName}The name of the series with a minimal of all the points y values.
{%xPercentOfSeries}The percentage of the series this point represents (Scatter Plot charts).
{%xPercentOfTotal}The percentage of all the series on the chart this point represents.
{%yPercentOfCategory}The percentage of all the points with the same name this point represents.

Formatting Parameters

Along with usage of special tokens which help to define the source of text, you can set options which help to format numeric values in the text. Options follow the token in curly brackets.

Here is a simple code with tokens:

// setting the tooltips with formatting
var columnTooltip = columnSeries.tooltip();
columnTooltip.format("{%seriesName}: {%value}{groupsSeparator:', decimalsCount:3}");

var lineTooltip = lineSeries.tooltip();
lineTooltip.format("{%seriesName}: {%value}{decimalsCount:1}%");

Here is a chart with a tooltip configured using tokens with options:

Playground

Formatting Parameters List

Here is the list of formatting parameters that allow organizing your data presentation in the way you prefer. In the Samples subsection, you can find samples showing how they work.

Option Type Description
decimalsCountnumericThe number of visible decimal characters (including characters for the integer values).
decimalPointbooleanSets a character for separating decimal part of a number.
groupsSeparatorstringSets a character for separating thousands of an integer number.
useBracketsForNegativeuseNegativeSignbooleanControls the "-" sign.
zeroFillDecimalsbooleanHides or displays decimal characters for integer values.
scaleScaling stringSets value scaling.
dateTimeFormatDatetime format stringSets datetime format.
typedatetime, time, date, number, string, percentSets value type, see Type section below.

Date/Time Syntax

The dateTimeFormat formatting parameter allows setting date/time patterns. Use the following syntax:

SymbolMeaningPresentationExample
Gera designatorAD
yyear1996
QquarterQ3 & 3rd quarter
Mmonth in yearJuly & 07
Lmonth in year (standalone)July & 07
dday in month10
hhour in am/pm (1~12)12
Hhour in day (0~23)0
mminute in hour30
ssecond in minute55
Sfractional second978
Eday of weekTue & Tuesday
cday of week (standalone)2 & Tues & Tuesday & T
wweek in year27
aam/pm markerPM
khour in day (1~24)24
Khour in am/pm (0~11)0
ztime zonePacific Standard Time
Ztime zone (RFC 822)-0800
vtime zone (generic)America/Los_Angeles
Vtime zoneLos Angeles Time
'escape for text'Date='
'single quote'o''clock'

Samples

In the next sample we have formatted the scale according to the Old British currency system (before 1971), when \u00a31 was equivalent to 20 shillings and 1 shilling = 12 pence.

var columnTooltip = columnSeries.tooltip();

// scaling value
columnTooltip.format("{%seriesName}: {%value}{scale:(1)(12)(20)|( p)( s)( \u00a3)}");

Here is a live sample with such settings:

Playground

If you explore the sample, you can see that all values are set in pence, but the shown value is formatted.

On the sample below there is another popular case of scale formatting shown: a thousandfold increase.

// string for formatting tooltips
var formatter = "{%seriesName}: {%value}{scale:(1)(1000)(1000)(1000)|( d)( th)( M)( B)}";

Here is a live sample with such settings:

Playground

Type

AnyChart engine tries to determine the best way to format values and provide the best defaults whenever possible. Also, when formatting parameters are used values are implicitly converted to another type.

In the following example different types of conversion and type formatting are shown:

// format the value and implicitly convert to date
chart.xAxis().labels().format('{%Value}{dateTimeFormat:MM-dd}');

// enable labels and explicitly specify time type
chart.labels().enabled(true);
chart.labels().format('{%x}{type:time}'); 
// explictly specify type in the title
chart.tooltip().titleFormat('{%x}{type:date}'); 
// use another type in the tooltip text
chart.tooltip().format('{%x}{type:number}'); 

Playground

Escaping symbols

If you want to use a symbol which is already reserved in token's parser, you need to use double slash (\) before this symbol to prevent it from been parsed.

var tooltip = series.tooltip();

// use coma as the thousands separator
tooltip.format("{%value}{groupsSeparator:\\,}");

Here is a live sample with such settings:

Playground

Formatting functions

For complex formatting use formatting function instead of token strings. Formatting functions are set like this:

// formatting using a function
var lineTooltip = lineSeries.tooltip();
lineTooltip.format(function() {
  return "Income: " + this.value/100 + "%";
});

Here is a live sample with such settings:

Playground

Note: you can use anychart.format.number(), anychart.format.dateTime() and other members of anychart.format namespace to format values in formatting functions:

var currentLabels = chart.labels();
// format the number
currentLabels.format(function () {
    return anychart.format.number(this.value, 3, ".", ",")
});

Here is a sample where anychart.format.number() is used to present label in a desired way:

Playground

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().format()
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 format() method with chart.label().
x
value
index

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

// enable chart labels
chart.labels(true);

// format labels
chart.labels().format(function() {
    return(this.seriesName + ": $" + this.value);
});

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(), getData() or getMeta(). Which one to use depends on the unique situation.

getData

Using these methods, you can display the values from the extra parameters, 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);

// use format
labels.format(function() {
    return(this.getData("extra_inf"));
});

Playground

In this sample we have added some extra information to the data: we defined the "extra&#95;inf" parameter of the "redundant" value for the second point of the second series and displayed it, using getData().

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 getData() 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.format(function() {
    return 
        this.seriesName + ": " + this.value + " millions" +
        "\nYear over year: " + this.getData("yoy") + "%";
});

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

Playground

Series Meta

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 format.

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.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.meta("company", "Duff B. Corp.");

// format

var labels_1 = series_1.labels();
labels_1.format(function() {
    return("C: "+this.series.meta("company")+"\nL: "+this.low+"\nH: "+this.high);
});

var labels_2 = series_2.labels();
labels_2.format(function() {
    return("C: "+this.series.meta("company")+"\nL: "+this.low+"\nH: "+this.high);
});

Playground

getStat

This method is to be used when you want to obtain various statistical information from a chart. Read more about this in Statistics article.

Here is a sample of the getStat() method used in a Pie chart.

// format
var labels = chart.labels();
labels.format(function() {
    return((this.getData("value"))+"(of "+this.getStat("sum")) + ")";
});

Playground