AnyChart Documentation
Still have questions?
Contact support
Still have questions?
Contact support

© 2024 AnyChart.Com All rights reserved.

Date and Time Formats

Overview

AnyChart supports flexible settings of both input and output date/time formats. In addition to a variety of built-in formats, it is possible to use custom formats.

This article explains how you can format and interpret input dates that you use in your data as well as how to format output dates that are displayed in various parts of the chart.

Input

Unix Timestamp

One of the available input formats is the Unix timestamp.

For example, January 15, 2018 is represented as 1515974400000.

In the sample below, this format is used to create a Gantt chart:

// create data
var data = [
  {
    id: "1",
    name: "Development",
    actualStart: 1515974400000,
    actualEnd: 1520640000000,
    children: [
      {
        id: "1_1",
        name: "Analysis",
        actualStart: 1515974400000,
        actualEnd: 1516838400000
      }
  ]}
];

Playground

Date.UTC()

The Date.UTC() JavaScript method allows setting the date or date/time. It returns the Unix timestamp, so it is equivalent to it.

For example, January 15, 2018 is represented as:

  • Date.UTC(2018,0,15)
  • Date.UTC(2018,0,15,0,0,0,0)

Sample Code

// create data
var data = [
  {
    id: "1",
    name: "Development",
    actualStart: Date.UTC(2018,0,15),
    actualEnd: Date.UTC(2018,2,10),
    children: [
      {
        id: "1_1",
        name: "Analysis",
        actualStart:  Date.UTC(2018,0,15),
        actualEnd:  Date.UTC(2018,0,25)
      }
  ]}
];

Date Object

You can set the date or date/time with the help of the Date object.

For example, January 15, 2018 is represented as:

  • new Date("2018-01-15")
  • new Date("2018-01-15T00:00:00.000Z")

Sample Code

// create data
var data = [
  {
    id: "1",
    name: "Development",
    actualStart: new Date("2018-01-15"),
    actualEnd: new Date("2018-03-10"),
    children: [
      {
        id: "1_1",
        name: "Analysis",
        actualStart: new Date("2018-01-15"),
        actualEnd: new Date("2018-01-25")
      }
  ]}
];

String

To set dates, you can use strings with dates or date/times. You should be very careful using this option, and understand the following section.

If you set input date/time format and input locale AnyChart follows the rules of pattern and locale to create a proper date.

If input date/time format and input locale are not defined explicitly, then AnyChart simply passes the string to Date objects constructor. It means that setting the string "2018-01-15" without specifying input date/time format is equivalent to using Date Object in the following way: new Date("2018-01-15"). The way date object interprets the string depends on the browser and user environement settings.

As a rule, to make sure that strings are interpreted correctly, you should always set:

Various date/time patterns can be used. For example: January 15, 2018 can be represented as:

  • "2018-01-15"
  • "2018-01-15T00:00:00.000Z"

Strings with the pattern above do not require any additional settings, but it is highly recommended to set the input date/time format. Otherwise, the way how dates are interpreted may be affected by users' browser settings.

Sample Code

// create data
var data = [
  {
    id: "1",
    name: "Development",
    actualStart: "2018-01-15",
    actualEnd: "2018-03-10",
    children: [
      {
        id: "1_1",
        name: "Analysis",
        actualStart: "2018-01-15",
        actualEnd: "2018-01-25"
      }
  ]}
];

inputDateTimeFormat()

When you use strings to set dates, specify the input date/time format to make sure that they are interpreted correctly.

Call the inputDateTimeFormat() method and pass a string with the date/time pattern used in your data:

anychart.format.inputDateTimeFormat("yyyy-MM-dd");

Also, make sure that you use the correct input locale.

The following sample shows how to set the input date format. Please note that it does not affect the output.

// create data
var data = [
  {
    id: "1",
    name: "Development",
    actualStart: "2018-01-15",
    actualEnd: "2018-03-10",
    children: [
      {
        id: "1_1",
        name: "Analysis",
        actualStart: "2018-01-15",
        actualEnd: "2018-01-25"
      }
  ]}
];

// set the input date/time format
anychart.format.inputDateTimeFormat("yyyy-MM-dd");

// create a data tree
var treeData = anychart.data.tree(data, "as-tree");

// create a chart
var chart = anychart.ganttProject();

// set the data
chart.data(treeData);

Playground

inputLocale()

When you use strings to set dates, the default input locale is automatically applied - en-us. If necessary, you can set any other locale listed in the Locales section on AnyChart CDN.

In the head section of your web page, place a link to the locale on your server or on AnyChart CDN:

<script src="https://cdn.anychart.com/locale/2.0.1/fr-fr.js"></script>

Then pass the code of the locale to the inputLocale() method:

anychart.format.inputLocale("fr-fr");

Please note: you should also set the input date/time format() after setting the locale.

This sample shows how the input locale fr-fr works:

// create data
var data = [
  {
    id: "1",
    name: "Development",
    actualStart: "15 janvier 2018",
    actualEnd: "10 mars 2018",
    children: [
      {
        id: "1_1",
        name: "Analysis",
        actualStart: "15 janvier 2018",
        actualEnd: "25 janvier 2018"
      }
  ]}
];

// set the input locale
anychart.format.inputLocale("fr-fr");

// set the input date/time format
anychart.format.inputDateTimeFormat("d MMMM yyyy");

// create a data tree
var treeData = anychart.data.tree(data, "as-tree");

// create a chart
var chart = anychart.ganttProject();

// set the data
chart.data(treeData);

Playground

Output

outputDateTimeFormat()

The default output date/time, date, and time formats affect the way how dates in various parts of the chart are formatted.

These formats are determined by the output locale you use - you can find them in the dateTimeLocale field of the locale. For example, here is how dates are formatted when the default en-us locale is applied:

  • dateTimeFormat: 'y MMM d \'at\' HH:mm:ss'
  • dateFormat: 'y MMM d'
  • timeFormat: 'HH:mm:ss'

To customize a format, pass a string with the date/time pattern you wish to use to one of these methods:

anychart.format.outputDateTimeFormat("d MMMM");

The following sample shows the output date/time format of the default locale works - for example, it affects tooltips. Also, please note that the output format is not affected by the input one.

// create data
var data = [
  {
    id: "1",
    name: "Development",
    actualStart: "2018-01-15",
    actualEnd: "2018-03-10",
    children: [
      {
        id: "1_1",
        name: "Analysis",
        actualStart: "2018-01-15",
        actualEnd: "2018-01-25"
      }
  ]}
];

// set the input date/time format
anychart.format.inputDateTimeFormat("yyyy-MM-dd");

// set the output date/time format
anychart.format.outputDateTimeFormat("d MMMM");

// create a data tree
var treeData = anychart.data.tree(data, "as-tree");

// create a chart
var chart = anychart.ganttProject();

// set the data
chart.data(treeData);

Playground

outputLocale()

The output locale determines the output date/time formats and affects the way how dates in various parts of the chart are formatted.

The default output locale is en-us. If necessary, you can set any other locale listed in the Locales section on AnyChart CDN.

In the head section of your web page, place a link to the locale on your server or on AnyChart CDN:

<script src="https://cdn.anychart.com/locale/2.0.1/fr-fr.js"></script>

Then pass the code of the locale to the outputLocale() method:

anychart.format.outputLocale("fr-fr");

The sample below shows how the output locale fr-fr works. For example, it affects tooltips and the timeline header.

// create data
var data = [
  {
    id: "1",
    name: "Development",
    actualStart: "2018-01-15",
    actualEnd: "2018-03-10",
    children: [
      {
        id: "1_1",
        name: "Analysis",
        actualStart: "2018-01-15",
        actualEnd: "2018-01-25"
      }
  ]}
];


// set the input date/time format
anychart.format.inputDateTimeFormat("yyyy-MM-dd");

// set the output locale
anychart.format.outputLocale("fr-fr");

// create a data tree
var treeData = anychart.data.tree(data, "as-tree");

// create a chart
var chart = anychart.ganttProject();

// set the data
chart.data(treeData);

Playground

format()

The following settings determine how dates in various parts of the chart are formatted:

You can override the output date/time format with the help of the format() method, combined with text formatters.

It is available for the following parts of the chart:

Tokens

You can format text by combining format() with tokens.

Here are some of the tokens that represent dates:

  • Project labels & tooltips - {%actualStart}, {%actualEnd}, {%baselineStart}, {%baselineEnd}
  • Resource labels & tooltips - {%start}, {%end}
  • Project & Resource header - {%tickValue}, {%end}

To format a date, add the dateTimeFormat formatting parameter after a token and specify the date/time pattern. This parameter is optional: if it is not set, the date are formatted according to the output date/time format.

In this sample, tokens are used to display and format dates in the second data grid column of a Project chart:

// set the text of the second data grid column
chart.dataGrid().column(1).labels().format(
  "{%actualStart}{dateTimeFormat:dd MMM} - {%actualEnd}{dateTimeFormat:d MMM}"
);

Playground

This following sample demonstrates that the output locale affects the way how tokens work:

// set the output locale
anychart.format.outputLocale("fr-fr");

// set the text of the second data grid column
chart.dataGrid().column(1).labels().format(
  "{%actualStart}{dateTimeFormat:dd MMM} - {%actualEnd}{dateTimeFormat:d MMM}"
);

Playground

Formatting Functions

You can format text by combining format() with formatting functions.

In these functions, a number of context fields is available that represent dates, for example:

  • Project labels & tooltips- actualStart, actualEnd, baselineStart, baselineEnd
  • Resource labels & tooltips - start, end
  • Project & Resource header - tickValue, end

These fields contain dates represented as Unix timestamps.

To format a date, pass it to the dateTime() method and specify the date/time pattern as the second parameter. This parameter is optional: if it is not set, the date is formatted according to the output date/time format.

In this sample, a formatting function is used to display and format dates in the second data grid column of a Project chart:

// set the text of the second data grid column
column_2.labels().useHtml(true);
column_2.labels().format(function() {
  var start = anychart.format.dateTime(this.actualStart, "dd MMM");
  var end = anychart.format.dateTime(this.actualEnd, "dd MMM");
  return "<span style='color:#64b5f6'>" + start +
         "</span> - <span style='color:#ffa000'>" + end + "</span>";
});

Playground

Column Presets

Using column presets is an alternative way to format dates displayed in data grid columns. Please keep in mind that presets can be applied only to dates set as Unix timestamps.

Learn more: Column Presets: Dates