Formatting date/time and numbers using "Intl" object

The Intl object is the namespace for the ECMAScript Internationalization API, which provides language sensitive string comparison, number formatting, and date and time formatting. This tutorial will show how you can use Intl options and locales for date/time and number formatting in place of string-based amCharts format definitions.

Intro

amCharts 5 uses DateFormatter and NumberFormatter objects to format date/time and numeric values respectively.

So, whenever date/time or a number needs to be formatted, the chart invokes an appropriate formatter.

By default formatters use string-based formats, e.g. "yyyy-MM-dd" (date/time); "#,###.00" (number).

However, formatters are not limited to that. Formats can also be set as objects representing format options from Intl specification.

Let’s look at each of the formatters separately.

Formatting date/time

Setting date format

The date format used by DateFormatter is set to its dateFormat property.

In a string-based config we would be setting it like this:

TypeScript
JavaScript

root.dateFormatter.set("dateFormat", "yyyy-MM-dd");

root.dateFormatter.set("dateFormat", "yyyy-MM-dd");

If we want browser’s Intl object to format it instead, we will set it to an object, e.g.:

TypeScript
JavaScript

root.dateFormatter.set("dateFormat", {
  weekday: "long",
  year: "numeric",
  month: "long",
  day: "numeric"
});

root.dateFormatter.set("dateFormat", {
  weekday: "long",
  year: "numeric",
  month: "long",
  day: "numeric"
});

Date format options

There are a lot of options available to format the dates.

Please refer to this Mozilla article for more info.

Setting for DateAxis

DateAxis deserves a honorable mention here because it does not use dateFormat value of the DateFormatter.

Instead it has its own set (two sets actually) of date formats that correspond to the day, hour, year, and other eventualities: dateFormats and periodChangeDateFormats.

In short, the concept of using Intl in DateAxis is the same: whenever you can set a date format, you can set it in Intl compatible object format. E.g.:

TypeScript
JavaScript

xAxis.get("dateFormats")["day"] = { year: "numeric", month: "short", day: "numeric" };
xAxis.get("periodChangeDateFormats")["day"] = { year: "numeric", month: "short", day: "numeric" };
xAxis.get("periodChangeDateFormats")["month"] = { year: "numeric", month: "short" };

xAxis.get("dateFormats")["day"] = { year: "numeric", month: "short", day: "numeric" };
xAxis.get("periodChangeDateFormats")["day"] = { year: "numeric", month: "short", day: "numeric" };
xAxis.get("periodChangeDateFormats")["month"] = { year: "numeric", month: "short" };

DateFormatter example

[todo]

Formatting numbers

Setting numberformat

Similarly to date format, numberis set via NumberFormatter property numberFormat.

Normally, using string formats, we would set it like this:

TypeScript
JavaScript

root.numberFormatter.set("numberFormat", "#,###.00");

root.numberFormatter.set("numberFormat", "#,###.00");

For numbers to be formatter via Intl object, we’ll need to set it using an object. E.g.:

TypeScript
JavaScript

root.numberFormatter.set("numberFormat", {
  style: "decimal",
  minimumFractionDigits: 2
});

root.numberFormatter.set("numberFormat", {
  style: "decimal",
  minimumFractionDigits: 2
});

Numberformat options

A list of available number formatting options is provided in this Mozilla article.

Specifying locales

As we already briefly mentioned in this tutorial, a formatter that is using Intl format will use user’s own OS locale to format the date/time an numbers. This might affect things like month and day names, decimal number separators, and other things.

We can provide our own locale (or a list of locales) for the formatter to use instead.

Both DateFormatter and NumberFormatter have intlLocales property, which is a string that accepts comma-separated list of locale codes, such as "en-US", "lt-LT", etc.

Say, we want to format our date/time or numbers using Austrian notation of German language. We would do something like this:

TypeScript
JavaScript

root.numberFormatter.set("intlLocales", "de-AT");

root.numberFormatter.set("intlLocales", "de-AT");