Hour Cycle and Dayperiod Options
You'll learn how to control 12-hour vs. 24-hour time display and customize AM/PM indicators when formatting dates.
When displaying times to users around the world, two major formatting preferences emerge: some cultures prefer 12-hour clocks with AM/PM indicators (like 3:00 PM), while others use 24-hour notation (like 15:00). The Intl.DateTimeFormat API gives you precise control over both aspects.
The hourCycle Option
The hourCycle option determines how hours are displayed:
'h12'— 12-hour clock (1–12)'h23'— 24-hour clock (0–23)'h11'— 12-hour clock (0–11, rare but used in some locales)'h24'— 24-hour clock (1–24, also rare)
const date = new Date('2024-03-15T15:30:00');
const format12 = new Intl.DateTimeFormat('en-US', {
hour: 'numeric',
hourCycle: 'h12'
});
const format24 = new Intl.DateTimeFormat('en-US', {
hour: 'numeric',
hourCycle: 'h23'
});
console.log(format12.format(date)); // "3 PM"
console.log(format24.format(date)); // "15"
The dayPeriod Option
The dayPeriod option adds context beyond simple AM/PM:
'narrow'— Shortest form (A, P)'short'— Abbreviated (AM, PM)'long'— Full words (in the morning, in the afternoon)
const formatter = new Intl.DateTimeFormat('en-US', {
hour: 'numeric',
dayPeriod: 'long'
});
console.log(formatter.format(date)); // "3 in the afternoon"
These options override locale defaults, giving you precise control when user preferences or design requirements demand specific time formats.
Key Takeaway: Use hourCycle to force 12-hour or 24-hour display, and dayPeriod to control how AM/PM or other day periods appear in your formatted times.