Formatters

Formatters are special helper pieces of functionality, that can format raw values accordingly to some some format.

Examples of formatters at work are labels on the Axes, rollover tooltip contents, value labels, and so on.

Formatters are applied automatically to all numeric, date and string values on the chart. You can also invoke them manually, through API or via special formatting directives in text templates.

Accessing formatters

Each and every chart in amCharts universe have four types of formatters, accessible via chart's properties:

Formatter	Property	Used for
DateFormatter	dateFormatter	Formatting dates
DurationFormatter	durationFormatter	Formatting duration values
NumberFormatter	numberFormatter	Formatting numeric values
TextFormatter	N/A	Formatting text

The fourth kind of formatter - TextFormatter - which does not have its own property for it does not have any configuration options, and is used to apply visual settings to SVG text. We'll discuss this special kind of formatter momentarily.

Formatting dates, numbers and durations

To set a format for a specific formatter use its *Format property.

This is better demonstrated in a table:

Formatter	Property / example
DateFormatter	chart.dateFormatter.dateFormat = "yyyy-MM-dd"	More info
DurationFormatter	chart.durationFormatter.durationFormat = "hh:ii:ss"	More info
NumberFormatter	chart.dateFormatter.numberFormat = "#,###.00"	More info

Now, whenever chart needs to display, say, a date, it turns to its dateFormatter, which in turn uses its dateFormat setting to do the actual formatting.

The same goes for other formatting types.

Click "More info" links for complete list of formatting options for the respective formatter.

Formatting text

Most of the places where text is displayed, there's also a way to set a "text template" of what to display.

A text template is a string of text, which can contain two types of formatting codes:

• Data fields;
• Visual formatting directives.

Data placeholders

Data placeholders are enclosed within curly brackets and contain reference to the fields in a data item.

Let's say we have a Date-based XY chart with a single Series in it and want the rollover tooltip to display "Date: Value" in it. We'd do it this way:

series.tooltipText = "{dateX}: {valueY}";

series.tooltipText = "{dateX}: {valueY}";

"series": [{
  // ...
  "tooltipText": "{dateX}: {valueY}"
]}

The first curly-bracket block indicates that we want to take the date value from the date-based X axis the Series is attached to. The date will be formatted using chart's dateFormatter, or more precisely what is set in formatter's dateFormat property.

The second block instructs us to take data point's value within Y axis (which in our case is a value axis) and replace it with a string representation of that value, formatted, yes you guessed it, by chart's numberFormatter, as set in its numberFormat setting.

There's more to data fields than this. Please refer to article "Formatting Strings" for more details.

Visual formatting

This type of formatting directives can add some visual flare to a plain text, like, set color, font weight and size, etc.

Visual formatting directives are put in square brackets. Let's make the value from previous example standout by making it bold:

series.tooltipText = "{dateX}: [bold]{valueY}[/]";

series.tooltipText = "{dateX}: [bold]{valueY}[/]";

"series": [{
  // ...
  "tooltipText": "{dateX}: [bold]{valueY}[/]"
]}

Again, there's a lot more of the formatting options. For a complete list, visit "Formatting Strings" article.

Overriding format in data fields

It is possible to override default formats directly within the data fields of the text template.

To do so, suffix the field with a proper formatting function:

Formatter	Property / example
DateFormatter	{dateX.formatDate("d MMM, yyyy")}
DurationFormatter	{valueY.formatDuration("ii:ss")}
NumberFormatter	{valueY.formatNumber("#,###.00")}

Individual formatters

Normally, chart's formatters are used for every single chart's element, so, for example, you can set how your numbers will be formatter once and have it applied to every single value label throughout the chart: axes, legend, labels, etc.

However, you can override formatters for any other object withing the chart individually. For example, you want all the numbers on your chart to be rounded to integer, but rounded to two decimals on a value axis. You go ahead and create a new NumberFormatter for this particular value axis, with the number formatting settings you need.

This could look like this:

// Round all numbers to integer
chart.numberFormatter.numberFormat = "#.";

// Create a separate NumberFormatter for avalue axis,
// and make it round axis label values to two decimals
yAxis.numberFormatter = new am4core.NumberFormatter();
yAxis.numberFormatter.numberFormat = "#.##";

// Round all numbers to integer
chart.numberFormatter.numberFormat = "#.";

// Create a separate NumberFormatter for avalue axis,
// and make it round axis label values to two decimals
yAxis.numberFormatter = new am4core.NumberFormatter();
yAxis.numberFormatter.numberFormat = "#.##";

{
  // ...
  // Round all numbers to integer
  "numberFormatter": {
    "numberFormat": "#."
  },

  // ...
  "yAxes": [{
    // ...
    // Create a separate NumberFormatter for avalue axis,
    // and make it round axis label values to two decimals
    "numberFormatter": {
      "type": "NumberFormatter",
      "forceCreate": true,
      "numberFormat": "#.##"
    }
  }]
}