What are the differences between the hourCycle options in Date.prototype.toLocaleTimeString()

Question

MDN documentation for toLocaleTimeString() indicates that the hourCycle and hc options have four possible values: "h11", "h12", "h23", & "h24".

Two of the possible values strike me as super obvious (i.e. "h12" and "h24"), but the other two, I have no idea what they do and my duckduckfoo/googlefoo is failing me!

What are the "h11" and "h23" values representing?

My best guess is that they are some type of 0 vs 1 derivations of "h12" and "h24", but the underlying date stamp is still the same, and the value logged is the same, so if this is it, where is the difference?

This should be documented, or at least linked to, on MDN's toLocalTimeString page or ECMAScript's toLocalTimeString page, but it's not. It also really strikes me as something that should be simple to figure out, and yet I’m not seeing the difference, and it’s now crawling under my skin!

const now = new Date();
console.log('hourCycle: h11', now.toLocaleTimeString('en-US', { hourCycle: 'h11' }))
console.log('hourCycle: h12', now.toLocaleTimeString('en-US', { hourCycle: 'h12' }))
console.log('hourCycle: h23', now.toLocaleTimeString('en-US', { hourCycle: 'h23' }))
console.log('hourCycle: h24', now.toLocaleTimeString('en-US', { hourCycle: 'h24' }))

Theodora

This only seems to work in Firefox. I wonder if it's not fully compatible and the MDN documentation is incomplete. Other doc sites don't even mention the option. – Vein

@Vein - The code snippet in the question does actually run in Chrome Version 73.0.3679.0 (Official Build) canary (64-bit). Like you, I'm unable to find any Google or Microsoft developer documentation on toLocaleTimeString or it's option (granted, I normally use MDN, so I'm a little out of water). – Theodora

Please note the issue that h24 is default: github.com/moment/luxon/issues/726 when hour12: false is specified – Hallucinatory

Answer 1

I found that the proposal of dateStyle and timeStyle options for Intl.DateTimeFormat says:

[[HourCycle]] is a String value indicating whether the 12-hour format ("h11", "h12") or the 24-hour format ("h23", "h24") should be used. "h11" and "h23" start with hour 0 and go up to 11 and 23 respectively. "h12" and "h24" start with hour 1 and go up to 12 and 24. [[HourCycle]] is only used when [[Hour]] is not undefined.

English or US style may prefer h12:

› new Date(2019,4,1,12,0,0).toLocaleString('en-US', { hourCycle: 'h12' })
‹ "5/1/2019, 12:00:00 PM"
› new Date(2019,4,1,12,0,0).toLocaleString('en-US', { hourCycle: 'h11' })
‹ "5/1/2019, 0:00:00 PM"

h24 must be used with caution. It would have been nice if the date part was the value one day before.

› new Date(2019,4,1,0,59,59).toLocaleString('ja-JP', { hourCycle: 'h23' })
‹ "2019/5/1 0:59:59"
› new Date(2019,4,1,0,59,59).toLocaleString('ja-JP', { hourCycle: 'h24' })
‹ "2019/5/1 24:59:59"

Compatibility table in MDN says Firefox 58 and Edge supports this.

Alphabetical

Answer 2

I agree it's currently difficult to find MDN's documentation on hourCycle values, but I found them here:

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Locale/hourCycle

Web technology for developers > JavaScript > JavaScript reference > Standard built-in objects > Intl.Locale > Intl.Locale.prototype.hourCycle

[…]

h12: Hour system using 1–12; corresponds to 'h' in patterns. The 12 hour clock, with midnight starting at 12:00 am.

h23: Hour system using 0–23; corresponds to 'H' in patterns. The 24 hour clock, with midnight starting at 0:00.

h11: Hour system using 0–11; corresponds to 'K' in patterns. The 12 hour clock, with midnight starting at 0:00 am.

h24: Hour system using 1–24; corresponds to 'k' in pattern. The 24 hour clock, with midnight starting at 24:00.

Accessible

I asked my question on Jan 18, 2019. The page that you reference was created May 17, 2019 [0]; a day shy of 4 months after I asked this question. Considering the page that you referenced didn't even exist when I asked for this information, I hope you can forgive me for not being able to find it. 😉 [0]: wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/… – Theodora

I found your above question in my search for an MDN doc on hourCycle, as they don't link to it from their pages on Date.prototype.toLocaleString() and on toLocaleTimeString(). Please know that I added my answer here to help, not to criticize. – Accessible

Answer 3

Many answers here referencing MDN, however the relevant standard is ECMA-402, so look there.

The hourCycle and hour12 options work as described in ECMA-402 §11.1.1 #40. The way they work in practice seems to be at odds with the specification.

What happens in various browsers is that setting hour12 to true or false means that the language default hour cycle may or may not be adopted, regardless of the hour cycle in the options.

A more reliable method is to set the hourCycle in the language tag, some examples:

// 1 Jan 2022 00:30
let d = new Date(2022,0,1,0,30);

// Specify only hour12: false, get default hour cycle for en-US
// Safari, Firefox 00:30:00
// Chrome 24:30:00
console.log(d.toLocaleTimeString('en-US',{hour12: false}));

// Specify only hourCycle: h24, forces hour12: false
// Safari, Firefox 24:30:00
// Chrome 24:30:00
console.log(d.toLocaleTimeString('en-US',{hourCycle: 'h24'}));

// Specify both, the default hourCycle is used
// Safari, Firefox 00:30:00
// Chrome 24:30:00
console.log(d.toLocaleTimeString('en-US',{hourCycle: 'h24', hour12: false}));

// All three browsers: 00:30:00
console.log(d.toLocaleTimeString('en-US-u-hc-h23'));

// All three browsers: 24:30:00
console.log(d.toLocaleTimeString('en-US-u-hc-h24'));

Trituration