Class: Time

// Apply time settings globally
Highcharts.setOptions({
    time: {
        timezone: 'Europe/London'
    }
});

// Apply time settings by instance
const chart = Highcharts.chart('container', {
    time: {
        timezone: 'America/New_York'
    },
    series: [{
        data: [1, 4, 3, 5]
    }]
});

// Use the Time object of a chart instance
console.log(
       'Current time in New York',
       chart.time.dateFormat('%Y-%m-%d %H:%M:%S', Date.now())
);

// Standalone use
const time = new Highcharts.Time({
   timezone: 'America/New_York'
});
const s = time.dateFormat('%Y-%m-%d %H:%M:%S', Date.UTC(2020, 0, 1));
console.log(s); // => 2019-12-31 19:00:00

Methods

dateFormat(format [, timestamp] [, upperCaseFirst])

Formats a JavaScript date timestamp (milliseconds since January 1 1970) into a human readable date string.

The format parameter accepts two types of values:

• An object containing settings that are passed directly on to Intl.DateTimeFormat.prototype.format.
• A format string containing either individual or locale-aware format keys. Individual keys, for example %Y-%m-%d, are listed below. Locale-aware keys are grouped by square brackets, for example %[Ymd]. The order of keys within the square bracket doesn't affect the output, which is determined by the locale. See example below. Internally, the locale-aware format keys are just a shorthand for the full object formats, but are particularly practical in templating where full object definitions are not an option.

The available string format keys are listed below. Additional formats can be given in the Highcharts.dateFormats hook.

Supported format keys:

Key	Description	Notes on locale-aware format
%A	Long weekday, like 'Monday'
%a	Short weekday, like 'Mon'
%E	Narrow weekday, single character
%d	Two digit day of the month, 01 to 31
%e	Day of the month, 1 through 31
%w	Day of the week, 0 through 6	N/A
%b	Short month, like 'Jan'
%B	Long month, like 'January'
%m	Two digit month number, 01 through 12
%o	Month number, 1 through 12
%y	Two digits year, like 24 for 2024
%Y	Four digits year, like 2024
%H	Two digits hours in 24h format, 00 through 23	Depending on the locale, 12h format may be instered.
%k	Hours in 24h format, 0 through 23	Depending on the locale, 12h format may be instered.
%I	Two digits hours in 12h format, 00 through 11	N/A. The locale determines the hour format.
%l	Hours in 12h format, 1 through 12	N/A. The locale determines the hour format.
%M	Two digits minutes, 00 through 59
%p	Upper case AM or PM	N/A. The locale determines whether to add AM and PM.
%P	Lower case AM or PM	N/A. The locale determines whether to add AM and PM.
%S	Two digits seconds, 00 through 59
%L	Milliseconds (naming from Ruby)

Parameters:

Name	Type	Argument	Default	Description
format	string | Highcharts.DateTimeFormatOptions			The desired string format where various time representations are prefixed with %, or an object representing the locale-aware format options.
timestamp	number	<optional>		The JavaScript timestamp.
upperCaseFirst	boolean	<optional>	false	Upper case first letter in the return.

Returns:

string .

The formatted date.

Example

// Object format, US English
const time1 = new Highcharts.Time({ locale: 'en-US' });
console.log(
    time1.dateFormat({
        day: 'numeric',
        month: 'short',
        year: 'numeric',
        hour: 'numeric',
        minute: 'numeric'
    }, Date.UTC(2024, 11, 31))
); // => Dec 31, 2024, 12:00 AM

// Object format, British English
const time2 = new Highcharts.Time({ locale: 'en-GB' });
console.log(
    time2.dateFormat({
        day: 'numeric',
        month: 'short',
        year: 'numeric',
        hour: 'numeric',
        minute: 'numeric'
    }, Date.UTC(2024, 11, 31))
); // => 31 Dec 2024, 00:00

// Individual key string replacement
const time3 = new Highcharts.Time();
console.log(
    time3.dateFormat('%Y-%m-%d %H:%M:%S', Date.UTC(2024, 11, 31))
); // => 2024-12-31 00:00:00

// Locale-aware keys, US English
const time4 = new Highcharts.Time({ locale: 'en-US' });
console.log(
    time4.dateFormat('%[YebHM]', Date.UTC(2024, 11, 31))
); // => Dec 31, 2024, 12:00 AM

// Locale-aware keys, British English
const time5 = new Highcharts.Time({ locale: 'en-GB' });
console.log(
    time5.dateFormat('%[YebHM]', Date.UTC(2024, 11, 31))
); // => 31 Dec 2024, 00:00

// Mixed locale-aware and individual keys
console.log(
    time5.dateFormat('%[Yeb], %H:%M', Date.UTC(2024, 11, 31))
); // => 31 Dec 2024, 00:00

getTimeTicks(normalizedInterval [, min] [, max] [, startOfWeek])

Return an array with time positions distributed on round time values right and right after min and max. Used in datetime axes as well as for grouping data on a datetime axis.

Parameters:

Name	Type	Argument	Default	Description
normalizedInterval	Highcharts.TimeNormalizedObject			The interval in axis values (ms) and the count
min	number	<optional>		The minimum in axis values
max	number	<optional>		The maximum in axis values
startOfWeek	number	<optional>	1

Returns:

Highcharts.AxisTickPositionsArray .

Time positions

getTimezoneOffset(timestamp)

Get the time zone offset based on the current timezone information as set in the global options.

Parameters:

Name	Type	Description
timestamp	number	The JavaScript timestamp to inspect.

Returns:

number .

The timezone offset in minutes compared to UTC.

makeTime(year, month [, date] [, hours] [, minutes] [, seconds])

Make a time and returns milliseconds. Similar to Date.UTC, but takes the current timezone setting into account.

Parameters:

Name	Type	Argument	Default	Description
year	number			The year
month	number			The month. Zero-based, so January is 0.
date	number	<optional>	1	The day of the month
hours	number	<optional>	0	The hour of the day, 0-23.
minutes	number	<optional>	0	The minutes
seconds	number	<optional>	0	The seconds

Returns:

number .

The time in milliseconds since January 1st 1970.

parse(s)

Parse a datetime string. Unless the string contains time zone information, apply the current timezone from options. If the argument is a number, return it.

Parameters:

Name	Type	Description
s	string | number | undefined	The datetime string to parse

Returns:

number | undefined .

Parsed JavaScript timestamp

toParts( [timestamp])

Get a date in terms of numbers (year, month, day etc) for further processing. Takes the current timezone setting into account. Inverse of makeTime and the native Date constructor and Date.UTC.

The date is returned in array format with the following indices:

0: year, 1: month (zero based), 2: day, 3: hours, 4: minutes, 5: seconds, 6: milliseconds, 7: weekday (Sunday as 0)

Parameters:

Name	Type	Argument	Description
timestamp	number | Date	<optional>	The timestamp in milliseconds since January 1st 1970. A Date object is also accepted.

Returns:

Array.<number> .

The date parts in array format.