Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / JavaScript

Time zones and hour cycles in Intl.DateTimeFormat

`timeZone` selects the local time to display for an instant, while `hourCycle` controls how the hour is numbered, including whether midnight appears as `00` or `24`.

Version: ECMAScript 2024 and the current web platform; runtime support varies

Syntax

new Intl.DateTimeFormat(locales, { timeZone, hourCycle, hour: "2-digit" })

The Intl.DateTimeFormat timeZone/hourCycle options answer two separate questions. timeZone selects the zone used to display an instant without changing the Date or its stored value. If omitted, it defaults to the runtime's time zone. A named zone like "America/New_York" uses the rules in effect at that instant, including daylight saving transitions. A fixed offset like "-05:00" does not follow those rules. Older runtimes may not support offset identifiers. timeZoneName controls the display label, not the choice of zone.

hourCycle sets the hour range: "h11" is 0–11, "h12" is 1–12, "h23" is 0–23, and "h24" is 1–24. In "h24", 24 labels the hour starting at midnight; it does not move the instant to the next day. hourCycle alone does not add an hour to the output: request one with hour or timeStyle, but do not combine the two.

If you set hour12: true or hour12: false, it takes precedence over both hourCycle and the locale's Unicode hc extension. true selects a 12-hour cycle; false selects a 24-hour cycle. To require a specific cycle, omit hour12 and set hourCycle, which takes precedence over hc. With none of these settings, the locale determines the default cycle.

An invalid hourCycle or an unrecognized timeZone identifier throws RangeError when the formatter is constructed, even if a valid hour12 would override hourCycle. Inspect the effective settings with resolvedOptions(); the cycle is absent if the format has no hour. To extract just the hour, use the hour part from formatToParts() rather than parsing the whole localized string.

Examples

const instant = new Date("2024-01-15T05:00:00Z");

function showHour(timeZone, hourCycle) {
  const formatter = new Intl.DateTimeFormat("en-US", {
    timeZone,
    hourCycle,
    hour: "2-digit",
    numberingSystem: "latn",
    formatMatcher: "basic",
  });
  const hour = formatter.formatToParts(instant).find(part => part.type === "hour");
  const displayHour = hour.value.padStart(2, "0");
  console.log(`${timeZone} ${formatter.resolvedOptions().hourCycle}: ${displayHour}`);
}

showHour("UTC", "h23");
showHour("America/New_York", "h23");
showHour("America/New_York", "h24");

Result

UTC h23: 05
America/New_York h23: 00
America/New_York h24: 24

The first two lines change only the zone: the same instant is hour `05` in UTC and midnight in New York. The final line changes only the cycle, so that same local hour is shown as `24` instead of `00`.

Related lessons

  • JavaScript · Lesson 25 · Advanced · Version: 4

Sources