Overview
Every geographical region has its own standard time zone. Each zone has a UTC offset, which is the difference in hours and minutes from Universal Coordinated Time (UTC). Many regions observe Daylight Saving Time (DST), where the offset changes during the seasons. Offset rules may also change for unpredictable political reasons.
JavaScript has no built-in functionality to manage multiple time zones, but it does have functionality to map between UTC and the user's local time zone, defined by the operating system.
The JavaScript Date constructor treats most input formats as local time. The exceptions are single dateStrings with a declared time zone and millisecond numbers, which use UTC. See the MDN Docs for more details.
If you are using timeNanoseconds, the value will remain the same regardless of the time zone.
Time Zones in KronoGraph
KronoGraph also has no built-in functionality to manage time zones, and will display dates exactly as they're passed in.
You will need to decide which time zone to use for KronoGraph events. The most common choices are either the user’s time zone or UTC.
See Scale Localization for information about displaying dates and times using different formats.
User Time Conversions
Sometimes users want to see dates in their local time zone. If your server stores dates with time zones, simply pass the dates directly to the client:
// serverside
const storedDate = '2016-05-22T15:58:33.592Z';
// send storedDate directly to clientThen create a JavaScript Date object:
// clientside
const dateToUse = new Date(storedDate);
timeline.markers([{ label: 'dateInLocalTime', time: dateToUse }]);KronoGraph will then display the date in the user’s time zone.
If your dates don’t have time zones, when JavaScript creates the date object it will assume the date is in local time already:
// clientside
// date string without a time zone
const zonelessDateString = 'Mon, 11 May 2015 15:00:00';
// date will be shown in the user’s time zone.
const dateInLocalTime = new Date(zonelessDateString);KronoGraph will then display the date as 3pm in the user’s time zone.
Server-side Conversions
If users are used to seeing dates in UTC or another time zone, you may want to convert the date to that time zone.
If users want dates in a specific time zone, it's best to convert on the server before sending the data.
We recommend using a library such as Moment.js to assist with managing time zone conversions.
For a date on the server:
// serverside
const storedDate = '2016-05-22T07:58:33.592Z';Convert this to local time on the server:
// serverside
const convertedDate = myCustomDateConverter(storedDate);
// send convertedDate to clientThe data arrives in local time:
// clientside
// this assumes convertedDate is a string
const dateToUse = new Date(convertedDate.time);
timeline.markers([{ label: 'dateInConvertedTime', time: dateToUse }]);Passing this value to KronoGraph will display dates in the converted time.
Millisecond Conversions
KronoGraph interprets numbers as time in milliseconds since January 1, 1970, 00:00:00 UTC, and displays them in UTC. This means they are shown as the same time for users in all time zones.
If you construct a date object with a millisecond number JavaScript will convert this to local time and you will get a different date than if you use the millisecond value itself:
// ms number is UTC
const milliseconds = 1431356400000;
const event1time = milliseconds;
// Date object is local time
const event2time = new Date(milliseconds);Dates returned by the timeline API are in local time. You can convert these back to milliseconds:
const returnedDate = new Date(2023, 0, 1, 14, 30); // local time
// convert to UTC milliseconds
const ms = Date.UTC(
returnedDate.getFullYear(),
returnedDate.getMonth(),
returnedDate.getDate(),
returnedDate.getHours(),
returnedDate.getMinutes(),
returnedDate.getSeconds(),
returnedDate.getMilliseconds(),
);
// 1672583400000