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 4 uses DateFormatter and NumberFormatter objects to format date/time and numeric values respectively.
MORE INFO To learn the concept of formatters, make sure you check out "Formatting Date & Time" 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 INFO Check 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:
chart.dateFormatter.dateFormat = "yyyy-MM-dd";
chart.dateFormatter.dateFormat = "yyyy-MM-dd";
{
// ...
"dateFormatter": {
"dateFormat": "yyyy-MM-dd"
}
}
If we want browser's Intl object to format it instead, we will set it to an object, e.g.:
chart.dateFormatter.dateFormat = {
"weekday": "long",
"year": "numeric",
"month": "long",
"day": "numeric"
};
chart.dateFormatter.dateFormat = {
"weekday": "long",
"year": "numeric",
"month": "long",
"day": "numeric"
};
{
// ...
"dateFormatter": {
"dateFormat": {
"weekday": "long",
"year": "numeric",
"month": "long",
"day": "numeric"
}
}
}
IMPORTANT By 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 INFO The 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.:
dateAxis.dateFormats.setKey("day", { "year": "numeric", "month": "short", "day": "numeric" });
dateAxis.periodChangeDateFormats.setKey("day", { "year": "numeric", "month": "short", "day": "numeric" });
dateAxis.periodChangeDateFormats.setKey("month", { "year": "numeric", "month": "short" });
dateAxis.dateFormats.setKey("day", { "year": "numeric", "month": "short", "day": "numeric" });
dateAxis.periodChangeDateFormats.setKey("day", { "year": "numeric", "month": "short", "day": "numeric" });
dateAxis.periodChangeDateFormats.setKey("month", { "year": "numeric", "month": "short" });
{
// ...
"xAxes": [{
"type": "DateAxis",
"dateFormats": {
"day": { "year": "numeric", "month": "short", "day": "numeric" }
},
"periodChangeDateFormats": {
"month": { "year": "numeric", "month": "short" },
"day": { "year": "numeric", "month": "short", "day": "numeric" }
}
}]
}
DateFormatter example
See the Pen amCharts 4: Using Intl object with DateFormatter and DateAxis by amCharts team (@amcharts) on CodePen.
Formatting numbers
IMPORTANT Number formatting via Intl is available in dev version only at this moment. It will also be available in the next stable public release: 4.7.7.
Setting numberformat
Similarly to date format, numberis set via NumberFormatter property numberFormat.
Normally, using string formats, we would set it like this:
chart.numberFormatter.numberFormat = "#,###.00";
chart.numberFormatter.numberFormat = "#,###.00";
{
// ...
"numberFormatter": {
"numberFormat": "#,###.00"
}
}
For numbers to be formatter via Intl object, we'll need to set it using an object. E.g.:
chart.numberFormatter.numberFormat = {
"style": "decimal",
"minimumFractionDigits": 2
};
chart.numberFormatter.numberFormat = {
"style": "decimal",
"minimumFractionDigits": 2
};
{
// ...
"numberFormatter": {
"numberFormat": chart.numberFormatter.numberFormat = {
"style": "decimal",
"minimumFractionDigits": 2
}
}
}
IMPORTANT By 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 INFO For 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:
chart.numberFormatter.intlLocales = "de-AT";
chart.numberFormatter.intlLocales = "de-AT";
{
// ...
"numberFormatter": {
// ...
"intlLocales": "de-AT"
}
}
NOTE Needless to say, setting intlLocales without setting numberFormat or dateFormat in an Intl object format will have no effect on the output.