Formatting dates

This tutorial takes a look at date formatter - helper object used to format date/time throughout the chart.

Formatter object

Date formatter object is accessible globally via chart root element's dateFormatter property.

We can use it to set dateFormat, as well as a few of other related settings, which will be used whenever date needs to be formatted in the chart.

Where is it used?

Date formatter is used in a number of places throughout the chart.

Some components like date axis their own logic to apply date formatting.

Labels (e.g. in tooltips) with date data placeholders will turn to date formatter to format their values.

Data export functionality will also use date formatter to format its output of date values.

The data processor will also use date formatter to parse string-based dates.

Global date format

Default format

A global date formatter will already have its dateFormat set to a default value, which may depend on the locale your chart is using.

Setting default format

Date format is set via formatter's dateFormat setting:

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

Formatting data placeholders

The values that will be shown in place of the placeholder will be formatted according to formatting settings as set out in global formatters or in-line functions.

We can set names of the data placeholders that hold numbers and need to be formatted as such via global formatter's dateFields setting:

root.dateFormatter.setAll({
  dateFormat: "yyyy-MM-dd",
  dateFields: ["valueX"]
});
root.dateFormatter.setAll({
  dateFormat: "yyyy-MM-dd",
  dateFields: ["valueX"]
});

For more information on how it works, please refer to "Data placeholders" tutorial.

Format codes

The following table outlines codes that can be used in date formats.

IMPORTANT Codes are case-sensitive.

NOTE Pay special attention to year codes. "yyyy" means year. "YYYY" means year of the week. Unless you know otherwise, you should probably always stick with "yyyy" (all lowercase).

NOTE The third column ("No.") deserves a little explanation. It indicates the number of times the code symbol can be repeated. For example, if the first row for "M" (month) shows "1..2", it means it can contain either one or two letters of "M". If it contains just one, the numbers will be shown how they are, e.g. 1, 5, 11, if it contains "MM", the resulting number will always be two-digits, e.g. 01, 05, 11.

PeriodCodeNo.ExampleComment
eraG1ADEra - Replaced with the Era string for the current date.
yeary1..n1996Calendar year.
Y1..n1997Year (of "Week of Year"), used in ISO year-week calendar. May differ from calendar year.
u1..n4601Extended year. This is a single number designating the year of this calendar system, encompassing all supra-year fields. For example, for the Julian calendar system, year numbers are positive, with an era of BCE or CE. An extended year value for the Julian calendar system assigns positive values to CE years and negative values to BCE years, with 1 BCE being year 0.
quarterq13Calendar quarter of the year starting from January.
monthM1..209Month number. "M" may produce one or two-digit numbers, whereas "MM" will always produce two-digit output, padding with a zero when necessary.
3SepShort month abbeviation.
4SeptemberFull month name.
5SFirst letter of the month.
weekw1..227Week of year.
W13Week of the month.
dayd1..21Day of the month.
D1..3345Day of the year.
F12Day of Week in Month. The example is for the 2nd Wed in July.
g1..n2451334Modified Julian day. This is different from the conventional Julian day number in two regards. First, it demarcates days at local zone midnight, rather than noon GMT. Second, it is a local number; that is, it depends on the local time zone. It can be thought of as a single number that encompasses all the date-related fields.
t1stDay ordinal: "st", "nd", "rd".
weekdayE1..23Day of the week. Using "EE" will prepend day number with a zero.
3TuesShort weekday name.
4TuesdayFull weekday name.
5TFirst letter of the weekday name.
e1..22Local day of week. Same as E except numeric value will depend on the local starting day of the week. For this example, Monday is the first day of the week.
3Tues
4Tuesday
5T
am/pma1AM"AM" or "PM".
2A.M."A.M." or "P.M.".
3A"A" or "P".
hourh1..211Hour [1-12].
H1..213Hour [0-23].
K1..20Hour [0-11].
k1..224Hour [1-24].
minutem1..259Minute. Using "mm" will pad one-digit numbers with a zero.
seconds1..212Second. Using "ss" will pad one-digit numbers with a zero.
S1..n3456Fractional Second - rounds to the count of letters. (example is for 12.34567)
A1..n69540000Milliseconds in day. This field behaves exactly like a composite of all time-related fields, not including the zone fields. As such, it also reflects discontinuities of those fields on DST transition days. On a day of DST onset, it will jump forward. On a day of DST cessation, it will jump backward. This reflects the fact that is must be combined with the offset field to obtain a unique local time value.
x11507908460868Timestamp (milliseconds since 1970-01-01).
n1..3029Milliseconds. Use one to three for zero padding. This is similar to "S" except number of letters determine padding of numbers instead of rounding.
zonez1PTTime zone. Short wall (generic) time.
2Pacific TimeTime zone. Long wall time.
3PDTTime zone. Short time zone abbreviation.
4Pacific Daylight TimeFull time zone name.
Z1GMT-08:00Time zone in GMT format.
2-0800Time zone in RFC 822 format.
otheri12017-10-14T05:24:17.872ZDate/time formatted according to ISO8601 format.
I1Sat, 14 Oct 2017 05:21:51 GMTDate/time formatted to a string representation using UTC time zone according to RFC-1123 specification.

Examples

FormatOutput
yyyy-MM-dd2021-07-17
MMM dt, yyyyJul 17th, 2021
HH:mm14:28

UTC and time zones

A number formatter can be made to recalculate all displayed dates into UTC or any other named time zone.

For this, we need to set utc or timezone settings of the root element:

root.utc = true;
root.utc = true;

For more information on setting time zones refer to "Root element: Time zone".

Styling text

Text formats can also include in-line styling instructions:

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

Please refer to the "Text styling and data binding" tutorial for more info.

Escaping

Quotes

To explicitly make formatter ignore a portion of text, enclose it within single quotes:

yyyy.MM.dd G 'at' HH:mm:ss zzz

The "at" above will not be parsed when being processed by a date formatter. It will be left as is:

2016.09.21 AD at 19:18:01 GMT+3

Any text enclosed in single quotes will be displayed as is, without applying formatting to it.

To use a single quote (either within quoted text or outside it) add single quote twice:

HH:mm:ss 'o''clock'

Will result in:

19:18:01 o'clock

Date formatting in charts

A date axis has its own special relationship with date formatting. It uses own collection of date formats for various occasions, and will ignore global date settings.

Please refer to "Date axis" tutorial for details.

Using Intl object formats

Date formats can be specified using JavaScript's built-in Intl object. Please refer to "Formatting date/time and numbers using “Intl” object" for further information.