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.

MORE INFOTo learn the concept of formatters, make sure you check out "Formatting dates" as well as "Formatting numbers" articles.

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.

MORE INFOCheck out intro to Intl object in Mozilla docs.

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:

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

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

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

IMPORTANTBy default date/time will be formatted to user's default locale specified in OS. We can override it by providing our own list of locale codes. This is described in section "Specifying locales" section later in this tutorial.

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.

MORE INFOThe above is described in great detail in DateAxis' own article.

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

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

Pardon the mess. We're still working on this section.

Formatting numbers

Setting numberformat

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

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

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

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

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

IMPORTANTBy default numbers will be formatted to user's default locale specified in OS. We can override it by providing our own list of locale codes. This is described in section "Specifying locales" section later in this tutorial.

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.

MORE INFOFor more info on locale codes check out Mozilla's "Locale identification and negotiation" article.

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

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

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

NOTESetting intlLocales without setting numberFormat or dateFormat in an Intl object format will have no effect on the output.